Skip to content

Configuration Files and Settings

Jump to bottom
Samera2022 edited this page Jan 30, 2026 · 1 revision

Configuration Files and Settings

Relevant source files

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. For information about runtime state caching (separate from configuration), see 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, 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.

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
Loading

Sources: 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, 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

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, README.md 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, README.md L80-L81

Storage Path Resolution Logic

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
Loading

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), and user navigation updates the cache.

Sources: README.md L80-L81, 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, 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

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

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
Loading

Sources: src/io/github/samera2022/mouse_macros/manager/ConfigManager.java L31-L44, 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:

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()
Loading

Sources: 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

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

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.

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
Loading

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, README.md 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

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

See also CacheManager

Example Configuration File

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

{
  "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

📝 MouseMacros - Java 鼠标宏录制和回放工具 | 📄 许可证: LGPL-3.0 | 🐛 报告问题 | ⭐ GitHub

最后更新: 2026-01-30

MouseMacros Wiki

📚 快速导航

入门

架构设计

宏录制与播放

配置与持久化

国际化与本地化

用户界面组件

工具类和助手

GitHub 仓库 | 问题反馈

Clone this wiki locally