Developer Guide

Development guidelines and compilation instructions for contributors and maintainers of FJ Flow.

---

Development Prerequisites

• Language: AutoHotkey v2 (v2.0 or higher recommended)
• OS: Windows 10 / 11

---

Project Structure

• fjFlow.ahk: Entry point for the Pro Edition. Handles configurations, custom GUIs, and JSON operations.
• fjFlowFree.ahk: Entry point for the Free Edition. Operates on internal default maps (KeyExtMap) without writing local files.
• lib/: Internal scripts, helper classes, and libraries.
• docs/images/: Image assets used in documentation and READMEs.
• docs/CaptureWorkflow.md: Automated screen capture and asset workflow guide.
• build.ps1: PowerShell script used to package the .exe releases.

---

Running from Source

1. Install AutoHotkey v2 on your Windows system.
2. Clone this repository.
3. Double-click fjFlow.ahk (Pro) or fjFlowFree.ahk (Free) to run.

---

Compiling (Building Executables)

To package the scripts into standalone .exe files, use the included PowerShell script.

Steps to Build

1. Open PowerShell and navigate to the repository root.
2. Run the build script:

   .\build.ps1

   [!IMPORTANT] Running build.ps1 uses the AutoHotkey compiler (Ahk2Exe) to output the standalone executables (fjFlow.exe and fjFlowFree.exe) into the build directory.

---

Important Development Conventions

When editing source code or submitting pull requests, follow these implementation rules:

1. Keyboard Layout (US/JIS) Detection

• Do not use the GetKeyboardType API to determine logical layout types. To handle setups where layouts are dynamically toggled in Windows settings, retrieve active HKL states using GetForegroundWindow and fall back to SystemParametersInfo(SPI_GETDEFAULTINPUTLANG) for default input language lookups.

2. Layered Window (WS_EX_LAYERED) Initialization Bug

• Layered windows with style WS_EX_LAYERED may fail to render on the first UpdateLayeredWindow call if they have never been initialized. To prevent this Windows bug, the GUI handles a dummy launch (Show("NA x0 y0 w1 h1") then Hide()) on startup to register the window buffers properly. Do not remove this initialization logic.

3. Key Hooks & Modifier Restorations

• When sending key events while key blocking (InputHook) is active, use SendEvent rather than SendInput to prevent modifier state restoration conflicts. Always declare SetKeyDelay(-1, -1) and temporarily halt (Stop()) the hook before sending keystrokes, resuming it with a delay (Sleep(50)) afterward.

4. Git Controls

• Running git operations that require authentication (e.g. git push, git pull) inside non-interactive shells will cause processes to hang indefinitely due to credential prompts. Restrict automated tasks to local commits, prompting the user to execute pushes manually in their terminal.