Documentation

Developer Guide

Information for developers to modify and build the FJ Flow source code.

Information for developers to modify and build the FJ Flow source code.

Development Environment & Requirements

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

Project Structure

The roles of the primary files and folders are as follows:

  • fjFlow.ahk: Entry point for the Pro version. Supports saving settings, GUI customization, and import/export.
  • fjFlowFree.ahk: Entry point for the Free version. A lightweight version that does not save settings and operates solely with the built-in default key extensions (KeyExtMap).
  • lib/: Classes and libraries used internally.
  • doc/: Documentation resources, including images and additional technical information.
  • build.ps1: PowerShell script for packaging the executable files (.exe).

Running from Source Code

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

Build Method (Compilation)

To create the .exe files for release, use build.ps1 located at the repository root.

Steps to Run the Build Command

  1. Open PowerShell and navigate to the repository root.
  2. Run the following command: 
    # Run in PowerShell
.\build.ps1

    [!IMPORTANT] Running build.ps1 compiles the code using the AutoHotkey compiler (Ahk2Exe) and outputs the Pro version fjFlow.exe and the Free version fjFlowFree.exe in the build directory.

Important Implementation Conventions & Specifications

When modifying the source code or submitting a pull request, please adhere to the following guidelines and bug workarounds.

1. Keyboard Layout (JIS/US) Detection

  • The GetKeyboardType API is not used for physical keyboard layout detection at startup. To accurately obtain the logical keyboard layout on the OS, the active thread’s HKL is retrieved via GetForegroundWindow. If that fails, a fallback detection retrieves the system default input language from SystemParametersInfo(SPI_GETDEFAULTINPUTLANG).

2. Workaround for Rendering Bug in Layered Windows (WS_EX_LAYERED)

  • Windows with the WS_EX_LAYERED style (such as the configuration guide and indicators) must be instantiated by being temporarily Shown at a dummy size (e.g., 1x1) and then Hided before calling the first UpdateLayeredWindow. If this process is removed, the OS will not allocate a drawing area, causing the window to remain transparent and fail to render.

3. Avoiding Conflicts Between Key Hooks and SendEvent

  • When synthesizing key events with modifier keys while the InputHook is active, SendEvent is used instead of SendInput to prevent input reversal bugs caused by conflict with automatic recovery. SetKeyDelay(-1, -1) must be explicitly set, and the hook must be temporarily Stopped completely before and after transmission.

4. Preventing Authentication Hangups During Git Operations

  • Executing commands that may prompt for authentication (such as git push or git pull) in non-interactive execution environments will cause background processes to hang indefinitely waiting for input. Keep automation limited to committing code, and prompt the user to manually perform remote push operations in an interactive terminal.