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__.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__.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.