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


TABLE OF CONTENTS
-----------------
  1.  Overview of the Window
  2.  Creating and Editing Pins
  3.  Quick Add Strip
  4.  Sorting and Filtering
  5.  Working with Files
  6.  Importing CSV / TSV Data
  7.  Merging Flag Pin Files
  8.  Exporting Flag Pins
  9.  Settings
  10. File Menu Reference
  11. Edit Menu Reference
  12. Settings Menu Reference
  13. Tools Menu Reference
  14. Keyboard Shortcuts
  15. The Flag Pin Fields
  16. Color Reference
  17. Troubleshooting


================================================================================
1.  OVERVIEW OF THE WINDOW
================================================================================

The Flag Pin Tool window has five horizontal sections from top to bottom:

Menu Bar
  Standard application menus: File, Edit, Settings, Tools, Help.

Toolbar
  Quick-access buttons for the most common actions:
    New, Open, Save, Save As
    Add…, Edit…, Delete, Duplicate
    Import CSV/TSV…, Export .flags.json…

Options Bar
  Live controls that affect the current session:
    Station:       Your callsign. Used as the default "Source" for new pins
                   and as "created_by" in exported files.
    Default color: The color pre-selected for new pins. Change at any time;
                   only affects pins created after the change.
    ▲ Up / ▼ Down: Reorder the selected pin in the list.
    Filter:        Type any text to narrow the list. The ✕ button clears it.
    Pin count:     Shows total pins, or "X / Y pins" when a filter is active.

Pin List (main area)
  A sortable table showing all flag pins. Columns:
    Description, Grid, Latitude, Longitude, Source, Color, Severity,
    Status, Blink, Date/Time (UTC)
  Row backgrounds are tinted with a pale shade of each pin's assigned color.
  Click a column header to sort; click again to reverse the order.
  Double-click any row (or press Enter) to open the Edit dialog.
  Multiple rows can be selected for Delete.

Quick Add Strip
  Rapid entry bar for creating pins without opening a dialog.
  See Section 3.

Status Bar
  Left: current status message.
  Center: "● Modified" indicator when there are unsaved changes.
  Right: path of the currently open file.


================================================================================
2.  CREATING AND EDITING PINS
================================================================================

Opening the Add / Edit Dialog
------------------------------
  - Toolbar: click Add… (to create) or Edit… (to edit selected pin)
  - Menu:    Edit > Add Flag Pin…  or  Edit > Edit Flag Pin…
  - Keyboard: Ins (Add),  Enter or double-click (Edit)

The dialog fields are described in full in Section 16. Key behaviors:

Grid ↔ Lat/Lon Auto-Sync
  Entering a Grid locator (e.g., EL99hc) automatically fills in Latitude
  and Longitude with the center of that grid square. Conversely, entering
  or editing Latitude and Longitude automatically recomputes the Grid.
  This works in real time as you type.

Now ▶ Button
  Sets the Date/Time field to the current UTC time in ISO 8601 format
  (YYYY-MM-DDTHH:MM:SSZ). Useful when placing a pin that represents the
  current situation.

Color Picker
  Choose from the named color list (Dark Red, Red, Orange, Yellow, Green,
  Dark Green, Cyan, Blue, Magenta, Purple, White, Black), or select
  "Custom…" at the bottom of the list to open the system color chooser
  and pick any arbitrary color. See Section 16 for the full color reference.

Blink
  When checked, the pin flashes on the map in JS8Reporter and MH Grid Mapper.
  Intended for urgent or time-sensitive markers.

Clicking OK
  Saves the pin to the list and closes the dialog. The list re-sorts and
  re-filters automatically. The newly added or edited pin is selected and
  scrolled into view.

Duplicating a Pin
  Edit > Duplicate (or Ctrl+D) copies the selected pin, appends " (copy)"
  to the description, assigns a new unique ID, and inserts it directly
  below the original. Useful for creating multiple pins at nearby locations.


================================================================================
3.  QUICK ADD STRIP
================================================================================

The Quick Add strip at the bottom of the window allows rapid pin entry
without opening a dialog for each pin. It is designed for situations where
you need to enter a batch of pins quickly from a list.

Fields in the Quick Add strip:
  Description   Required. The pin label.
  Grid          Maidenhead locator (e.g., EL99hc). Latitude and Longitude
                auto-fill when you finish typing a valid grid.
  Lat / Lon     Decimal degrees. Filled automatically from Grid. You can
                also enter coordinates directly if no Grid is available.
  Color         Color picker (swatch + dropdown). Defaults to the Default
                color from the options bar.

Clicking Add ▶
  Creates the pin and adds it to the list immediately. The Description and
  Grid fields clear, ready for the next entry. Latitude, Longitude, and Color
  retain their last values as a convenience for entering nearby pins.

Source is set to the Station callsign from the options bar.
Severity, Status, and Blink are left at defaults. Use Edit… afterward if
you need to set those fields for a quick-add pin.

If Grid is not valid and no Lat/Lon is entered, an error message is shown
and the pin is not created.


================================================================================
4.  SORTING AND FILTERING
================================================================================

Sorting
-------
  Click any column header in the pin list to sort by that column ascending.
  Click the same header again to sort descending. The current sort is lost
  when you reorder rows manually with Move Up / Move Down.

  Numeric sort is applied to Latitude and Longitude columns. All other
  columns sort alphabetically (case-insensitive).

Filtering
---------
  Type in the Filter field in the options bar to narrow the list to rows
  that contain the typed text in any of these fields:
    Description, Grid, Source, Severity, Status, Color (name or hex)

  The filter is applied live as you type. The pin count in the options bar
  changes to "X / Y pins" to show how many are visible vs. total.

  Click ✕ or clear the field to remove the filter and show all pins.

  Note: Filter affects only the display. All pins are still present in the
  file regardless of what the filter shows. Sorting and filtering do not
  affect the save order — pins are saved in the order they appear in the
  (unfiltered) list, which is the insertion/move order.


================================================================================
5.  WORKING WITH FILES
================================================================================

New  (Ctrl+N)
  Clears the current pin list and starts an unnamed new file. If there are
  unsaved changes, you are prompted to save first.

Open…  (Ctrl+O)
  Opens a .flags.json file. The existing pin list is replaced by the file
  contents. If there are unsaved changes, you are prompted to save first.
  The file dialog defaults to the import folder from Settings.

Save  (Ctrl+S)
  Saves the current pin list to the currently open file. If no file is open
  (new, unsaved file), behaves like Save As.

Save As…  (Ctrl+Shift+S)
  Saves the pin list to a new file path. Prompts for a location and filename.
  The suggested filename is:
      flags_<CALLSIGN>_<YYYYMMDD_HHMMSS>.flags.json
  The file dialog defaults to the export folder from Settings.

  After Save As, the newly named file becomes the current file.

Unsaved Changes
  The title bar shows " *" after the filename when there are unsaved changes.
  The status bar shows "● Modified" in red. Any action that would discard
  changes (New, Open, Exit) prompts to save first.

File Format
  All files use the sitrep_flags v1.0 JSON format (see Section 16 and the
  Program Overview for the format specification). Files are plain text and
  can be opened in any text editor for inspection or manual editing.


================================================================================
6.  IMPORTING CSV / TSV DATA
================================================================================

Flag Pin Tool can import data from any comma-separated (CSV) or
tab-separated (TSV) file, regardless of what program produced it.

Opening the Import Dialog
--------------------------
  Toolbar: click Import CSV/TSV…
  Menu:    File > Import CSV/TSV…

  The file dialog accepts .csv, .tsv, and .txt files. Flag Pin Tool
  auto-detects the delimiter from the file extension and content.

Column Mapping Dialog
----------------------
  After selecting a file, the Column Mapping dialog opens. It shows:

  Column Mapping (left)
    Each column from your CSV file is listed with a dropdown. Flag Pin Tool
    auto-guesses the assignment based on common header names (e.g., a column
    named "description", "desc", or "name" is mapped to Description; a column
    named "lat" or "latitude" maps to Latitude). Review and adjust any that
    were guessed incorrectly.

    Available target fields:
      (skip)       — ignore this column
      Description  — pin label (required for a meaningful pin)
      Grid         — Maidenhead locator (e.g., EL99hc)
      Latitude     — decimal degrees
      Longitude    — decimal degrees
      Date/Time    — ISO 8601 UTC (YYYY-MM-DDTHH:MM:SSZ) or any date string
      Source       — origin callsign or identifier
      Color        — hex (#CC3300) or color name (see Section 16)
      Severity     — Low / Medium / High / Critical (or blank)
      Status       — Active / Ongoing / Resolved (or blank)

  Data Preview (right/bottom)
    Shows the first few rows of the file so you can confirm the mapping
    before importing.

  Click Import to apply. Click Cancel to abort.

Location Requirement
  At minimum, each imported row must have either:
    - A valid Grid value (Maidenhead, 4–6 characters)
    - Both Latitude and Longitude values (decimal degrees)
  Rows with neither are skipped and counted in the "X row(s) skipped" message.
  If neither location field is mapped at all, Import is blocked with an error.

Defaults Applied to Imported Rows
  - Source:      Station callsign from the options bar (if not mapped)
  - Color:       Default color from the options bar (if not mapped or blank)
  - Description: "(imported)" (if not mapped or blank)
  - Date/Time:   Current UTC time (if not mapped or blank)
  - Severity, Status, Blink: blank / false (if not mapped)

After Import
  Imported pins are appended to the current pin list. The existing pins are
  not replaced. A summary message shows how many pins were added and how many
  rows were skipped. The file is marked as modified (unsaved).


================================================================================
7.  MERGING FLAG PIN FILES
================================================================================

File > Merge Flag Pins (.flags.json)…

  Merges the contents of an existing .flags.json file into the current list.
  This is different from Open, which replaces the entire list.

Merge Logic
  - Pins in the incoming file that do not exist in the current list (matched
    by their unique id) are added.
  - Pins that already exist are updated only if the incoming pin's updated_at
    timestamp is newer than the current pin's updated_at. Older versions
    are silently ignored.

  This is the same merge logic used by JS8Reporter and MH Grid Mapper, so
  pin files can be exchanged freely without worrying about overwriting newer
  edits with older versions.

  A summary message shows how many pins were added and how many were updated.
  The list is marked as modified after any merge that results in changes.


================================================================================
8.  EXPORTING FLAG PINS
================================================================================

File > Export .flags.json…  (also on toolbar as "Export .flags.json…")

  Always prompts for a file path — this is a separate export copy of the data
  and does not change which file is currently open for Save/Save As. Use Export
  when you want to produce a file for import into JS8Reporter or MH Grid Mapper
  without modifying your working document.

  The suggested filename is:
      flags_export_<CALLSIGN>_<YYYYMMDD_HHMMSS>.flags.json
  The file dialog defaults to the export folder from Settings.

  The exported file includes the station callsign (from the options bar or
  Settings) in the "created_by" field of the file header.

  Export is blocked (with a warning) if the pin list is empty.

Using the Exported File
  To import the exported file into JS8Reporter:
    Open JS8Reporter → File > Export Flag Pins… is outbound only.
    To import: View > Flag Pins… → Import…, then select the .flags.json file.

  To import into MH Grid Mapper:
    File > Import Flag Pins…, then select the .flags.json file.
    Or: View > Flag Pins… → Import…


================================================================================
9.  SETTINGS
================================================================================

Settings > Settings… opens the Settings dialog with three tabs.

General Tab
-----------
  Station callsign
    Your amateur radio callsign. Stored in uppercase. Used as:
      - "created_by" in all saved and exported .flags.json files
      - Default "Source" value for new pins created via Add… or Quick Add
      - Pre-filled in the suggested export filename

  Default pin color
    The color pre-selected in all new pin dialogs and in the Quick Add strip.
    Changing this does not affect existing pins.

Folders Tab
-----------
  Default import folder
    The folder the file dialog opens to when using Open…, Import CSV/TSV…,
    and Merge Flag Pins….
    Default: flagpintool/data/imports/

  Default export folder
    The folder the file dialog opens to when using Save As… and
    Export .flags.json….
    Default: flagpintool/data/exports/

  Browse… opens a folder picker for each field. Leave blank to use the
  default data/ subdirectories.

Auto-Update Tab
---------------
  Check for updates on startup
    When enabled (default), Flag Pin Tool checks the version check URL in the
    background at startup. If a newer version is found, a dialog offers to
    open the download page in your browser. No data is transmitted other than
    the HTTP request for the version file.

  Version check URL
    The URL of the version.json file to compare against. The default is:
        https://sitrepnet.com/flagpintool-download/version.json
    Leave blank to disable all automatic update checks entirely.

Settings > Check for Updates Now
  Runs an immediate version check regardless of whether the startup check is
  enabled. Shows a "you're up to date" or "check failed" message in addition
  to prompting about an available update.


================================================================================
10. FILE MENU REFERENCE
================================================================================

New                            Start a new empty pin list.
Open…                          Open a .flags.json file.
Save                           Save to the current file (prompts if new).
Save As…                       Save to a new file path.
Import CSV/TSV…                Import pins from a CSV or TSV file.
Merge Flag Pins (.flags.json)… Add/update pins from another .flags.json file.
Export .flags.json…            Export a copy for use in JS8Reporter / MH Grid Mapper.
Exit                           Save settings and close the program.


================================================================================
11. EDIT MENU REFERENCE
================================================================================

Add Flag Pin…       Open the Add dialog to create a new pin.
Edit Flag Pin…      Open the Edit dialog for the selected pin.
Delete              Delete the selected pin(s) (with confirmation).
Duplicate           Copy the selected pin, inserting it below the original.
Select All          Select all pins in the (filtered) list.
Delete Selected     Same as Delete when multiple rows are selected.
Move Up             Move the selected pin one position up in the list.
Move Down           Move the selected pin one position down in the list.


================================================================================
12. SETTINGS MENU REFERENCE
================================================================================

Settings…               Open the Settings dialog (callsign, folders, updates).
Check for Updates Now   Run an immediate version check against the server.


================================================================================
13. TOOLS MENU REFERENCE
================================================================================

Grid Converter…
  Opens the Grid Converter dialog, which converts between Maidenhead grid
  locators, MGRS/USNG military grid coordinates, and decimal Lat/Lon.

  Enter any of the following in the Input field and click Convert (or press
  Enter) — the format is auto-detected:
    Maidenhead    e.g.  EL99hc
    MGRS / USNG   e.g.  15RYP53780
    Lat, Lon      e.g.  34.5678, -86.1234

  Results displayed:
    Detected format  —  Maidenhead, MGRS, or Lat/Lon
    Maidenhead       —  Grid square (4, 6, or 8 characters)
    MGRS / USNG      —  Military grid reference
    Latitude         —  Decimal degrees N/S
    Longitude        —  Decimal degrees E/W

  Options:
    MGRS precision     —  10 m (default) / 100 m / 1 km / 10 km
    Maidenhead length  —  6-char (default) / 4-char / 8-char

  Buttons: Copy Maidenhead, Copy MGRS, Close.

  Note: the Grid Converter requires the mgrs Python package
  (pip3 install mgrs). The rest of Flag Pin Tool works without it.


================================================================================
14. KEYBOARD SHORTCUTS
================================================================================

Ctrl+N          New file
Ctrl+O          Open file
Ctrl+S          Save
Ctrl+Shift+S    Save As
Ins             Add pin
Enter           Edit selected pin (also double-click)
Del             Delete selected pin(s)
Ctrl+D          Duplicate selected pin
Ctrl+A          Select all pins
Alt+Up          Move selected pin up
Alt+Down        Move selected pin down


================================================================================
15. THE FLAG PIN FIELDS
================================================================================

Each flag pin stores the following fields:

id  (UUID, auto-generated)
  Unique identifier for the pin. Assigned automatically and never changes.
  Used for deduplication during merge operations.

description  (required)
  A short label describing the pin. Displayed prominently in the list and
  on the map in JS8Reporter and MH Grid Mapper. There is no length limit,
  but short labels display better on maps.

grid  (Maidenhead locator)
  The Maidenhead grid locator for the pin's position. Accepts 4-character
  (e.g., EL99) or 6-character (e.g., EL99hc) locators. A 6-character locator
  is much more precise and recommended.

  Grid and Lat/Lon auto-sync in the edit dialog: entering one updates the
  others automatically.

lat / lon  (decimal degrees)
  Latitude and Longitude in decimal degrees (e.g., 29.10417, -81.375).
  Negative longitude = West. Negative latitude = South.

datetime  (UTC, ISO 8601)
  The date and time the pin was placed or the event occurred, in UTC.
  Format: YYYY-MM-DDTHH:MM:SSZ  (e.g., 2026-06-14T12:00:00Z)
  Defaults to the current UTC time when a new pin is created.

source
  The originating station, agency, or operator. Free text. Defaults to the
  Station callsign from the options bar or Settings.

color  (hex)
  The pin display color in standard hex notation (#RRGGBB). Shown as a color
  name in the list (e.g., "Dark Red"). See Section 16 for the full list.
  Custom colors (any hex value) are supported via the "Custom…" option.

blink  (true / false)
  When true, the pin flashes on the map in JS8Reporter and MH Grid Mapper.
  Use sparingly; intended for urgent or time-sensitive markers.

severity  (optional)
  Urgency level of the situation at the pin location.
  Accepted values: (blank), Low, Medium, High, Critical.

status  (optional)
  Current state of the situation at the pin location.
  Accepted values: (blank), Active, Ongoing, Resolved.

updated_at  (UTC, ISO 8601, auto-managed)
  The last time this pin was modified. Set automatically by Flag Pin Tool
  whenever a pin is created or edited. Used by the merge logic to determine
  which version of a pin is newer. Do not edit this field manually.


================================================================================
16. COLOR REFERENCE
================================================================================

Named colors available in the color picker:

  Name          Hex
  ----------    --------
  Dark Red      #CC3300   (default)
  Red           #FF0000
  Orange        #FF8800
  Yellow        #FFFF00
  Dark Green    #228B22
  Green         #00FF00
  Cyan          #00FFFF
  Blue          #0000FF
  Magenta       #FF00FF
  Purple        #800080
  White         #FFFFFF
  Black         #000000

Select "Custom…" at the bottom of the color dropdown to open the system color
chooser and select any color not in this list.

CSV Import Color Values
  When importing from CSV, the Color column accepts either:
    - A hex code:    #CC3300
    - A color name:  Dark Red  (case-insensitive match against the list above)
  If the value is blank or unrecognized, the default color from the options
  bar is used.


================================================================================
17. TROUBLESHOOTING
================================================================================

Grid locator not recognized (in Add/Edit dialog or Quick Add)
-------------------------------------------------------------
  Maidenhead locators must be 4 or 6 characters in the form:
      two letters  +  two digits  +  (optionally) two letters
  Examples: EL99, EL99hc, EM80rf
  The letters are A–R (field), the digits 0–9 (square), and the second pair
  of letters is A–X (subsquare). Common errors: letters outside range,
  incorrect length, digits and letters swapped.

Lat/Lon fields show unexpected values after typing a grid
---------------------------------------------------------
  The auto-sync updates Lat/Lon as soon as a valid grid is recognized while
  you type. If you want to enter Lat/Lon manually instead, clear the Grid
  field first so the auto-sync does not overwrite your values.

Import shows "0 pins imported" from a CSV file
-----------------------------------------------
  The most common cause is that no row has a valid location. Check:
  1. The column mapping dialog assigned Grid or (Latitude + Longitude) correctly.
  2. The Grid values use Maidenhead format (e.g., EL99hc, not a US state name).
  3. Latitude and Longitude values are decimal degrees (e.g., 29.10, not
     degrees-minutes-seconds format such as 29°06'15"N).

Exported file not recognized by JS8Reporter or MH Grid Mapper
-------------------------------------------------------------
  Verify the file was saved using Save, Save As, or Export .flags.json…
  These produce a file starting with:
      { "format": "sitrep_flags", "version": "1.0", ...
  If the file was exported from a spreadsheet program, re-import it using
  Import CSV/TSV… and then re-export using Export .flags.json…

Sorting does not work as expected after moving rows manually
-------------------------------------------------------------
  Move Up / Move Down set a manual order. Clicking a column header to sort
  re-applies the sort on top of that order. If you want to restore the
  manual order, click Sort by a blank column (there is none) — or simply
  use Move Up / Move Down again after sorting.

The pin list is filtered and I can't see all pins
-------------------------------------------------
  Clear the Filter field in the options bar, or click the ✕ button next to
  it. The filter is display-only and never deletes data.

"● Modified" shows even though I just saved
-------------------------------------------
  If you edit a pin or use Quick Add immediately after saving, the modified
  indicator reappears. It reflects the live state of the data vs. the saved
  file. Save again (Ctrl+S) to clear it.

Settings are not saved between sessions
----------------------------------------
  Settings are saved when the program closes normally (File > Exit or the
  window close button with "Yes" to save). If the program is force-killed,
  settings from the current session may not be written. Use File > Exit to
  close normally.
