Getting Started

Getting Started

Relevant source files

• README.md
• src/io/github/samera2022/mouse_macros/MouseMacro.java
• src/io/github/samera2022/mouse_macros/UpdateInfo.java
• src/io/github/samera2022/mouse_macros/constant/OtherConsts.java

Purpose and Scope

This document provides installation instructions, system requirements, and a quick start guide for using MouseMacros. It covers the initial setup process, first launch behavior, and basic macro recording/playback workflows. For detailed information about specific components, see Architecture Overview. For comprehensive configuration options, see Configuration and Persistence.

---

System Requirements

MouseMacros is a cross-platform Java application with the following requirements:

Component	Requirement
Java Runtime	JRE 1.8 or higher
Operating Systems	Windows, macOS, Linux
Native Library	JNativeHook (bundled)
Disk Space	~35 MB (EXE version), ~2 MB (JAR version)
Permissions	Global input capture requires administrative privileges on some systems

The application uses the JNativeHook native library to capture system-wide mouse and keyboard events, which is automatically configured during initialization.

Sources: README.md L42, MouseMacro.java L11-L15

---

Installation

JAR Version

For users who prefer running the JAR directly:

1. Verify Java Installation: Ensure JRE 1.8+ is installed by running: java -version If Java is not installed, download it from Oracle's website.
2. Download: Obtain the latest MouseMacros.jar from the GitHub Releases page.
3. Launch: Execute the JAR file either by: * Double-clicking the JAR file (if file associations are configured) * Running from command line: java -jar MouseMacros.jar

EXE Version

For users who prefer a standalone executable (Windows only):

1. Download: Obtain the latest MouseMacros.exe from the GitHub Releases page.
2. Launch: Double-click the EXE file. The bundled JRE and all dependencies are included (~34 MB total size).

Important: Do not rename the EXE file. The packaged executable relies on the original filename to locate startup resources.

Sources: README.md L41-L50, UpdateInfo.java L97-L106

---

First Launch and Initialization

Initialization Sequence

When MouseMacros starts, the following initialization process occurs:

sequenceDiagram
  participant User
  participant MouseMacro["MouseMacro.main()"]
  participant ConfigDir["CONFIG_DIR"]
  participant LibDir["libs/"]
  participant JNativeHook
  participant MainFrame
  participant MouseMacro
  participant ConfigDir
  participant LibDir

  User->>MouseMacro: "Launch Application"
  MouseMacro->>ConfigDir: "Get CONFIG_DIR path"
  note over ConfigDir: "Platform-specific:
  MouseMacro->>LibDir: "Check libs/ directory"
  loop ["Directory missing"]
    MouseMacro->>LibDir: "Create libs/ directory"
  end
  MouseMacro->>MouseMacro: "Set jnativehook.lib.path property"
  note over MouseMacro: "System.setProperty(
  MouseMacro->>JNativeHook: "Load native library"
  MouseMacro->>MainFrame: "Launch UI on EDT"
  MainFrame->>User: "Display MainFrame window"

Loading

Sources: MouseMacro.java L10-L17

Directory Structure Created

On first launch, MouseMacros creates the following directory structure in the platform-specific application data location:

MouseMacros/
├── config.cfg          # User preferences and settings
├── cache.json          # Runtime state (window sizes, recent paths)
├── libs/
│   └── JNativeHook.x86_64.dll  # Native hook library
└── [user-defined macro storage directory]

File	Purpose	Format
config.cfg	Stores UI language, theme mode, hotkey mappings, default storage path, execution settings	JSON
cache.json	Stores recent file paths, window dimensions, close operation preference	JSON

The directory paths are platform-specific:

Platform	Location
Windows	%LOCALAPPDATA%\MouseMacros
macOS	~/Library/Application Support/MouseMacros
Linux	~/.local/share/MouseMacros

Note: The %USERPROFILE%/AppData/MouseMacros/ path mentioned in some documentation should be corrected to %LOCALAPPDATA%/MouseMacros/.

Sources: README.md L66-L67, MouseMacro.java L12

---

Basic Usage Workflow

Overview of Macro Operations

MouseMacros provides four core operations, each controlled by hotkeys (default mappings shown):

flowchart TD

StartRec["Start Recording<br>(F2)"]
StopRec["Stop Recording<br>(F3)"]
Save["Save to .mmc file<br>(UI button)"]
Load["Load from .mmc file<br>(UI button)"]
Play["Play Macro<br>(F4)"]
Abort["Abort Operation<br>(F5)"]

subgraph subGraph0 ["Macro Lifecycle"]
    StartRec
    StopRec
    Save
    Load
    Play
    Abort
    StartRec --> StopRec
    StopRec --> Save
    Save --> Load
    Load --> Play
    Play --> Abort
end

Loading

Sources: README.md L60-L62

Step-by-Step: Recording Your First Macro

1. Adjust Window Size (First Launch Only)

On first launch, the window may not display all buttons properly due to language-specific text lengths. Resize the MainFrame window to ensure all UI elements are visible.

flowchart TD

Launch["First Launch"]
Check["All buttons<br>visible?"]
Resize["Resize MainFrame"]
Configure["Proceed to Configuration"]

Launch --> Check
Check --> Resize
Check --> Configure
Resize --> Configure

Loading

Sources: README.md L57-L58

2. Configure Settings (Recommended)

Before recording, open the Settings dialogs to configure:

• SettingsDialog: Set language, theme, default storage path, enable Quick Mode
• MacroSettingsDialog: Configure repeat times and repeat delays

Access these via buttons in MainFrame:

• "Settings" button → Opens SettingsDialog
• "Macro Settings" button → Opens MacroSettingsDialog

Note: Hotkeys can be customized in SettingsDialog. Default hotkeys are:

• F2: Start Recording
• F3: Stop Recording
• F4: Play Macro
• F5: Abort Operation

Sources: README.md L59

3. Record Actions

To record a macro:

1. Press F2 (or configured "Start Recording" hotkey) or click the "Start Recording" button in MainFrame
2. Perform mouse clicks, keyboard inputs, and scroll wheel actions
3. Press F3 (or configured "Stop Recording" hotkey) or click the "Stop Recording" button

During recording:

• Mouse button clicks (left, right, middle) are captured
• Keyboard key presses are captured
• Scroll wheel movements are captured
• Mouse coordinates and timing between actions are recorded

sequenceDiagram
  participant User
  participant MainFrame
  participant MacroManager
  participant GlobalMouseListener

  User->>MainFrame: "Press F2 or click Start Recording"
  MainFrame->>MacroManager: "startRecording()"
  note over MacroManager: "recording = true
  loop ["User performs actions"]
    User->>GlobalMouseListener: "Mouse/Keyboard event"
    GlobalMouseListener->>MacroManager: "recordAction(MouseAction)"
    MacroManager->>MacroManager: "Add action to list
  end
  User->>MainFrame: with timestamp"
  MainFrame->>MacroManager: "Press F3 or click Stop Recording"
  note over MacroManager: "recording = false"

Loading

Sources: README.md L60

4. Save the Macro

After recording:

1. Click the "Save Macro" button in MainFrame
2. A JFileChooser dialog appears
3. Choose a destination and filename
4. The macro is saved as a .mmc file (CSV format)

The file location behavior depends on the enableDefaultStorage setting:

• If enabled: The file chooser opens to defaultMmcStoragePath (configured in SettingsDialog)
• If disabled: The file chooser opens to the last used save directory (cached in cache.json)

Sources: README.md L61

5. Load and Play the Macro

To replay a saved macro:

1. Click the "Load Macro" button in MainFrame
2. Select a .mmc file from the file chooser
3. Click the "Play Macro" button or press F4

Playback behavior is controlled by settings:

• Quick Mode (enableQuickMode): If enabled, actions execute without delays between them
• Custom Macro Settings (enableCustomMacroSettings): If enabled, the macro repeats repeatTime times with repeatDelay seconds between each repetition

Emergency Stop: Press F5 (Abort Operation) to immediately stop playback.

Sources: README.md L62

---

Understanding the Main Interface

MainFrame Components

The MainFrame window provides the primary interface for macro operations:

flowchart TD

ButtonPanel["Button Panel"]
LogArea["Log Display Area"]
MenuBar["Menu Bar"]
SystemTray["System Tray Integration"]
StartBtn["Start Recording (F2)"]
StopBtn["Stop Recording (F3)"]
PlayBtn["Play Macro (F4)"]
AbortBtn["Abort Operation (F5)"]
SaveBtn["Save Macro"]
LoadBtn["Load Macro"]
SettingsBtn["Settings"]
MacroSettingsBtn["Macro Settings"]
LogMessages["Action logs and status messages"]

ButtonPanel --> StartBtn
ButtonPanel --> StopBtn
ButtonPanel --> PlayBtn
ButtonPanel --> AbortBtn
ButtonPanel --> SaveBtn
ButtonPanel --> LoadBtn
ButtonPanel --> SettingsBtn
ButtonPanel --> MacroSettingsBtn
LogArea --> LogMessages

subgraph subGraph2 ["Status Display"]
    LogMessages
end

subgraph subGraph1 ["Button Panel Actions"]
    StartBtn
    StopBtn
    PlayBtn
    AbortBtn
    SaveBtn
    LoadBtn
    SettingsBtn
    MacroSettingsBtn
end

subgraph MainFrame ["MainFrame Window"]
    ButtonPanel
    LogArea
    MenuBar
    SystemTray
end

Loading

Global Hotkeys

Global hotkeys work even when MainFrame is minimized or in the background:

Hotkey	Function	Description
F2	Start Recording	Begin capturing mouse and keyboard events
F3	Stop Recording	End recording session
F4	Play Macro	Execute loaded macro
F5	Abort Operation	Emergency stop during playback

Note: All hotkeys are customizable in the Settings dialog.

Sources: README.md L28-L31

System Tray Integration

When MainFrame is closed, the application minimizes to the system tray rather than exiting. This allows global hotkeys to remain active. To fully exit the application, use the system tray icon's context menu.

Sources: UpdateInfo.java L75

---

Configuration Files

Configuration Overview

MouseMacros uses two JSON files for persistence:

flowchart TD

ConfigFile["config.cfg"]
CacheFile["cache.json"]
Appearance["Appearance Settings:<br>- followSystemSettings<br>- lang<br>- enableDarkMode<br>- allowLongStr<br>- readjustFrameMode"]
Storage["Storage Settings:<br>- enableDefaultStorage<br>- defaultMmcStoragePath"]
Execution["Execution Settings:<br>- enableQuickMode<br>- enableCustomMacroSettings<br>- repeatTime<br>- repeatDelay"]
Hotkeys["Hotkey Mappings:<br>- keyRecord<br>- keyStop<br>- keyPlay<br>- keyAbort<br>- keyMap"]
RecentPaths["Recent Paths:<br>- lastSaveDirectory<br>- lastLoadDirectory"]
WindowState["Window State:<br>- windowSizeMap<br>- defaultCloseOperation"]

ConfigFile --> Appearance
ConfigFile --> Storage
ConfigFile --> Execution
ConfigFile --> Hotkeys
CacheFile --> RecentPaths
CacheFile --> WindowState

subgraph subGraph2 ["Runtime State"]
    RecentPaths
    WindowState
end

subgraph subGraph1 ["Configuration Categories"]
    Appearance
    Storage
    Execution
    Hotkeys
end

subgraph subGraph0 ["Persistent Storage"]
    ConfigFile
    CacheFile
end

Loading

Key Configuration Options

The following table summarizes critical settings that affect basic usage:

Setting	Key	Default	Description
Follow System Settings	followSystemSettings	true	Automatically use OS language and theme
Enable Quick Mode	enableQuickMode	false	Ignore timing delays between actions (dangerous without proper abort hotkey)
Enable Default Storage	enableDefaultStorage	false	Always use configured default path for file operations
Default Storage Path	defaultMmcStoragePath	<user documents>	Default location for saving/loading .mmc files
Enable Custom Macro Settings	enableCustomMacroSettings	false	Enable repeat count and delay settings
Repeat Times	repeatTime	1	Number of times to execute macro
Repeat Delay	repeatDelay	0.0	Seconds to wait between repetitions (supports 3 decimal places)

Sources: README.md L74-L90

---

Next Steps

After completing this getting started guide, explore:

• Architecture Overview - Understand the application's internal structure
• Macro Recording and Playback - Deep dive into macro operations
• Configuration and Persistence - Complete configuration reference
• Internationalization and Localization - Language support details
• User Interface Components - Detailed UI documentation

Sources: README.md L38-L106