# Configuration Files and Settings

> **Relevant source files**
> * [README.md](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md)
> * [src/io/github/samera2022/mouse_macros/UpdateInfo.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/UpdateInfo.java)
> * [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java)
> * [src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java)

## Purpose and Scope

This page documents the structure and content of the `config.cfg` file, the configuration categories available to users, and how each setting affects application behavior. For information about the `ConfigManager` class that manages these settings, see [ConfigManager](ConfigManager). For information about runtime state caching (separate from configuration), see [CacheManager](CacheManager).

---

## Configuration File Overview

The application stores persistent user preferences in a JSON-formatted file named `config.cfg`. This file is located in a platform-specific application data directory:

| Platform | Default Location |
| --- | --- |
| Windows | `%LOCALAPPDATA%\MouseMacros\config.cfg` |
| macOS | `~/Library/Application Support/MouseMacros/config.cfg` |
| Linux | `~/.local/share/MouseMacros/config.cfg` |

The configuration file is automatically created with default values if it does not exist when the application starts. All settings are persisted in JSON format using Google's Gson library for serialization.

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L25-L29](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L25-L29), [README.md L66-L72](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L66-L72)

---

## Configuration Data Structure

The configuration is represented by the `Config` class, which contains all persistent user preferences. The class is defined as a nested static class within `ConfigManager`.

```mermaid
classDiagram
    class Config {
        +boolean followSystemSettings
        +String lang
        +boolean enableDarkMode
        +boolean enableDefaultStorage
        +String defaultMmcStoragePath
        +boolean enableQuickMode
        +boolean allowLongStr
        +String readjustFrameMode
        +Map<String,String> keyMap
        +boolean enableCustomMacroSettings
        +int repeatTime
        +double repeatDelay
    }
    class ConfigManager {
        +Config config
        +loadConfig() : Config
        +saveConfig(Config)
        +reloadConfig()
        +getAvailableLangs() : String[]
    }
    class SettingsDialog {
        +JCheckBox followSysBox
        +JComboBox langCombo
        +JCheckBox darkModeBox
        +JCheckBox enableDefaultStorageBox
        +JTextField pathField
        +JCheckBox quickModeBox
        +JCheckBox allowLongStrCheckBox
        +JComboBox rfmCombo
    }
    class MacroSettingsDialog {
        +JCheckBox enableCustomBox
        +JSpinner repeatTimeSpinner
        +JSpinner repeatDelaySpinner
    }
    ConfigManager --> Config : manages
    SettingsDialog --> ConfigManager : reads/writes
    MacroSettingsDialog --> ConfigManager : reads/writes
```

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L31-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L31-L44)

---

## Configuration Categories

The configuration settings are logically organized into four categories: Appearance, Storage, Execution, and Hotkeys.

### Appearance Settings

These settings control the visual presentation of the application, including language, theme mode, tooltip behavior, and window sizing.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `followSystemSettings` | `boolean` | `true` | When true, overrides `lang` and `enableDarkMode` with OS-detected values |
| `lang` | `String` | `"zh_cn"` | Language code (e.g., "en_us", "zh_cn", "ja_jp", "ko_kr", "ru_ru", "es_es", "fr_fr") |
| `enableDarkMode` | `boolean` | `false` | When true, applies dark color scheme; when false, applies light scheme |
| `allowLongStr` | `boolean` | `false` | Controls tooltip display width: false = wrapped to fixed width, true = long single line |
| `readjustFrameMode` | `String` | `"STANDARDIZED"` | Controls window sizing behavior: `"MIXED"`, `"STANDARDIZED"`, or `"MEMORIZED"` |

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L32-L39](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L32-L39), [README.md L77-L84](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L77-L84)

#### Follow System Settings Behavior

When `followSystemSettings` is `true`, the application uses `SystemUtil` to detect the OS language and dark mode preference, ignoring the `lang` and `enableDarkMode` fields. This creates a hierarchical relationship where system detection takes precedence over explicit configuration.

**Sources:** [src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java L51-L96](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java#L51-L96)

#### Readjust Frame Mode

The `readjustFrameMode` setting determines how the application handles window sizing when language changes. The three modes are:

* `RFM_MIXED` (`"MIXED"`): Blends historical cached size with recommended size
* `RFM_STANDARDIZED` (`"STANDARDIZED"`): Always uses recommended size based on content
* `RFM_MEMORIZED` (`"MEMORIZED"`): Always uses cached historical size

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L21-L23](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L21-L23), [README.md L84](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L84-L84)

### Storage Settings

These settings control where macro files (`.mmc` files) are saved and loaded by default.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `enableDefaultStorage` | `boolean` | `false` | When true, `defaultMmcStoragePath` is used; when false, cached last-used directories apply |
| `defaultMmcStoragePath` | `String` | `""` | Absolute path to default folder for save/load dialogs |

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L35-L36](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L35-L36), [README.md L80-L81](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L80-L81)

#### Storage Path Resolution Logic

```mermaid
flowchart TD

Start["User clicks 'Save Macro' or 'Load Macro'"]
CheckDefault["enableDefaultStorage == true?"]
CheckPath["defaultMmcStoragePath exists?"]
CreateDir["Attempt to create directory"]
UseDefault["JFileChooser opens at defaultMmcStoragePath"]
CheckCache["lastSaveDirectory or lastLoadDirectory cached?"]
UseCache["JFileChooser opens at cached path"]
UseUserDocs["JFileChooser opens at user Documents folder"]
SaveCache["Save selected directory to cache"]
IgnoreCache["Do not update cache"]

Start --> CheckDefault
CheckDefault --> CheckPath
CheckDefault --> CheckCache
CheckPath --> UseDefault
CheckPath --> CreateDir
CreateDir --> UseDefault
CheckCache --> UseCache
CheckCache --> UseUserDocs
UseDefault --> IgnoreCache
UseCache --> SaveCache
UseUserDocs --> SaveCache
```

When `enableDefaultStorage` is `true`, the file chooser always opens at `defaultMmcStoragePath`, and user navigation does not update the cached directories. When `false`, the file chooser uses cached paths from `cache.json` (see [CacheManager](CacheManager)), and user navigation updates the cache.

**Sources:** [README.md L80-L81](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L80-L81), [src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java L150-L208](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java#L150-L208)

### Execution Settings

These settings control macro playback behavior and timing.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `enableQuickMode` | `boolean` | `false` | When true, ignores recorded delays between actions |
| `enableCustomMacroSettings` | `boolean` | `false` | When true, enables `repeatTime` and `repeatDelay` |
| `repeatTime` | `int` | `1` | Number of times to repeat macro execution |
| `repeatDelay` | `double` | `0` | Delay in seconds between repetitions (supports 3 decimal places) |

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L37-L43](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L37-L43), [README.md L82-L90](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L82-L90)

#### Quick Mode Warning

When `enableQuickMode` is `true`, the `MacroManager` skips all delays recorded during macro capture, executing actions as rapidly as possible. This can cause unexpected behavior if macros interact with applications that require time to process events. The README strongly advises setting an abort hotkey before enabling this mode.

**Sources:** [README.md L82](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L82-L82)

### Hotkey Settings

Hotkey mappings are stored in the `keyMap` field, which is a `Map<String, String>` mapping action names to key codes.

| Key Name | Default | Function |
| --- | --- | --- |
| `key_record` | (varies) | Start recording macro |
| `key_stop` | (varies) | Stop recording macro |
| `key_play` | (varies) | Play recorded macro |
| `key_abort` | (varies) | Abort currently running macro |

The hotkey configuration is managed through the `HotkeyDialog` (accessed via `SettingsDialog`). Users can customize these keys to avoid conflicts with other applications.

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L40](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L40-L40), [README.md L28-L31](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L28-L31)

---

## Configuration Impact on Application Subsystems

The following diagram shows how configuration settings flow from the `Config` object to various application subsystems.

```mermaid
flowchart TD

ConfigFile["config.cfg<br>(JSON on disk)"]
Config["Config object<br>(in memory)"]
AppearanceSubsystem["Appearance Subsystem"]
StorageSubsystem["Storage Subsystem"]
ExecutionSubsystem["Execution Subsystem"]
HotkeySubsystem["Hotkey Subsystem"]
TooltipSubsystem["Tooltip Subsystem"]
WindowSubsystem["Window Sizing Subsystem"]
ComponentUtil["ComponentUtil<br>Theme application"]
Localizer["Localizer<br>Translation system"]
SystemUtil["SystemUtil<br>OS query"]
MacroManager["MacroManager<br>saveToFile()/loadFromFile()"]
JFileChooser["JFileChooser<br>Save/Load dialogs"]
MacroManagerPlay["MacroManager<br>play() method"]
GlobalMouseListener["GlobalMouseListener<br>Hotkey detection"]
CustomToolTipWindow["CustomToolTipWindow<br>Tooltip rendering"]
ComponentUtilAdjust["ComponentUtil<br>adjustFrameWithCache()"]

ConfigFile --> Config
Config --> AppearanceSubsystem
Config --> StorageSubsystem
Config --> ExecutionSubsystem
Config --> HotkeySubsystem
Config --> TooltipSubsystem
Config --> WindowSubsystem
AppearanceSubsystem --> ComponentUtil
AppearanceSubsystem --> Localizer
AppearanceSubsystem --> SystemUtil
StorageSubsystem --> MacroManager
StorageSubsystem --> JFileChooser
ExecutionSubsystem --> MacroManagerPlay
HotkeySubsystem --> GlobalMouseListener
TooltipSubsystem --> CustomToolTipWindow
WindowSubsystem --> ComponentUtilAdjust
```

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L31-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L31-L44), [src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java L230-L248](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java#L230-L248)

---

## Settings Modification Workflow

Users modify configuration settings through the `SettingsDialog` and `MacroSettingsDialog` windows. The following sequence shows the typical workflow:

```mermaid
sequenceDiagram
  participant User
  participant MainFrame
  participant SettingsDialog
  participant Config
  participant ConfigManager
  participant Localizer
  participant ComponentUtil
  participant ConfigFile

  User->>MainFrame: Click "Settings" button
  MainFrame->>SettingsDialog: new SettingsDialog()
  SettingsDialog->>Config: Read current values
  Config-->>SettingsDialog: followSystemSettings, lang, enableDarkMode, etc.
  SettingsDialog->>User: Display settings UI
  User->>SettingsDialog: Modify settings (checkboxes, combos, text fields)
  User->>SettingsDialog: Click "Save Settings"
  SettingsDialog->>Config: Update fields (config.lang = ...)
  SettingsDialog->>ConfigManager: saveConfig(config)
  ConfigManager->>ConfigFile: Write JSON to config.cfg
  SettingsDialog->>ConfigManager: reloadConfig()
  ConfigManager->>Config: Reload from disk
  SettingsDialog->>Localizer: load(config.lang)
  Localizer->>Localizer: Reload translation map
  SettingsDialog->>MainFrame: refreshMainFrameTexts()
  MainFrame->>Localizer: Fetch new translations
  SettingsDialog->>ComponentUtil: setMode(darkMode or lightMode)
  ComponentUtil->>SettingsDialog: Apply theme to dialog
  ComponentUtil->>MainFrame: Apply theme to main frame
  SettingsDialog->>SettingsDialog: dispose()
```

**Sources:** [src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java L230-L249](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/frame/SettingsDialog.java#L230-L249)

---

## Configuration Validation and Defaults

### Validation Logic

The `ConfigManager` performs minimal validation when loading configuration:

1. **File Existence**: If `config.cfg` does not exist, a new `Config` object with default values is created and saved.
2. **Empty File**: If the file exists but is empty or contains invalid JSON, a default `Config` is created.
3. **Missing Fields**: Gson automatically provides default values for any missing fields during deserialization.

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L49-L63](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L49-L63)

### Default Values Table

| Setting | Default Value | Rationale |
| --- | --- | --- |
| `followSystemSettings` | `true` | Respects user's OS preferences by default |
| `lang` | `"zh_cn"` | Developer's primary language |
| `enableDarkMode` | `false` | Light mode is more universally compatible |
| `enableDefaultStorage` | `false` | Allows flexible file navigation initially |
| `defaultMmcStoragePath` | `""` (empty) | User must explicitly configure |
| `enableQuickMode` | `false` | Safety: requires explicit user opt-in |
| `allowLongStr` | `false` | Prevents tooltips from extending off-screen |
| `readjustFrameMode` | `"STANDARDIZED"` | Provides consistent window sizing |
| `keyMap` | `{}` (empty map) | Populated during first run |
| `enableCustomMacroSettings` | `false` | Single execution is default |
| `repeatTime` | `1` | Execute once |
| `repeatDelay` | `0` | No delay between repetitions |

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L32-L43](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L32-L43)

---

## Available Languages Detection

The `ConfigManager` provides a utility method `getAvailableLangs()` that scans the `lang/` directory (or JAR resource path) for available translation files. This method is used to populate the language selection combo box in `SettingsDialog`.

```mermaid
flowchart TD

Start["getAvailableLangs() called"]
CheckDevMode["Localizer.isDevMode()?"]
DevPath["Scan filesystem: lang/ directory"]
JarPath["Scan JAR resources: lang/ entries"]
ListFiles["List .json files"]
ExtractNames["Extract filename without .json extension"]
ReturnArray["Return String[] array"]

Start --> CheckDevMode
CheckDevMode --> DevPath
CheckDevMode --> JarPath
DevPath --> ListFiles
JarPath --> ListFiles
ListFiles --> ExtractNames
ExtractNames --> ReturnArray
```

Supported languages as of version 1.2.2:

* `en_us` (English - United States)
* `zh_cn` (Chinese - Simplified)
* `ja_jp` (Japanese)
* `ko_kr` (Korean)
* `ru_ru` (Russian)
* `es_es` (Spanish)
* `fr_fr` (French)

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L79-L132](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L79-L132), [README.md L32](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L32-L32)

---

## Configuration Persistence Strategy

The configuration persistence follows a simple write-on-save strategy:

1. **Loading**: Configuration is loaded once during static initialization of `ConfigManager` via the static initializer block.
2. **Modification**: The `Config` object is modified in-memory by UI dialogs.
3. **Saving**: When the user clicks "Save Settings", the entire `Config` object is serialized to JSON and written to `config.cfg`.
4. **Reloading**: After saving, `reloadConfig()` is called to ensure the in-memory state matches the disk state.

The configuration file is formatted with pretty-printing enabled via `GsonBuilder.setPrettyPrinting()`, making it human-readable and manually editable if necessary.

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L18-L76](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L18-L76)

---

## Relationship with Cache

It's important to distinguish configuration from cache:

| Aspect | Configuration (`config.cfg`) | Cache (`cache.json`) |
| --- | --- | --- |
| **Purpose** | Persistent user preferences | Ephemeral runtime state |
| **Managed By** | `ConfigManager` | `CacheManager` |
| **Typical Data** | Language, theme, hotkeys, execution settings | Window sizes, last-used directories |
| **User Control** | Directly editable through Settings dialogs | Indirectly modified through usage |
| **Durability** | Preserved across reinstalls (in user data directory) | Can be deleted to reset UI state |

The `enableDefaultStorage` setting creates a key interaction between config and cache: when enabled, cached directory paths are ignored in favor of the configured default path.

**Sources:** [README.md L69-L72](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L69-L72)

 See also [CacheManager](CacheManager)

---

## Example Configuration File

Below is an example `config.cfg` file with typical values:

```json
{
  "followSystemSettings": false,
  "lang": "en_us",
  "enableDarkMode": true,
  "enableDefaultStorage": true,
  "defaultMmcStoragePath": "C:\\Users\\Username\\Documents\\MouseMacros",
  "enableQuickMode": false,
  "allowLongStr": false,
  "readjustFrameMode": "STANDARDIZED",
  "keyMap": {
    "key_record": "F2",
    "key_stop": "F3",
    "key_play": "F4",
    "key_abort": "F5"
  },
  "enableCustomMacroSettings": true,
  "repeatTime": 5,
  "repeatDelay": 1.5
}
```

This configuration represents a user who:

* Has disabled system settings following to use explicit preferences
* Uses English language with dark mode
* Has enabled default storage pointing to a custom Documents subfolder
* Has configured standard F-key hotkeys (F2-F5)
* Has enabled custom macro settings to repeat 5 times with 1.5 second delays

**Sources:** [src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L31-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/manager/ConfigManager.java#L31-L44)