# Getting Started

> **Relevant source files**
> * [README.md](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md)
> * [src/io/github/samera2022/mouse_macros/MouseMacro.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/MouseMacro.java)
> * [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/constant/OtherConsts.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/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](Architecture-Overview). For comprehensive configuration options, see [Configuration and Persistence](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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L42-L42), [MouseMacro.java L11-L15](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L41-L50), [UpdateInfo.java L97-L106](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/UpdateInfo.java#L97-L106)

---

## First Launch and Initialization

### Initialization Sequence

When MouseMacros starts, the following initialization process occurs:

```mermaid
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"
```

**Sources:** [MouseMacro.java L10-L17](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/MouseMacro.java#L10-L17)

### Directory Structure Created

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

```markdown
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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L66-L67), [MouseMacro.java L12](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/MouseMacro.java#L12-L12)

---

## Basic Usage Workflow

### Overview of Macro Operations

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

```mermaid
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
```

**Sources:** [README.md L60-L62](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/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.

```mermaid
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
```

**Sources:** [README.md L57-L58](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L59-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

```mermaid
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"
```

**Sources:** [README.md L60](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L60-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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L61-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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L62-L62)

---

## Understanding the Main Interface

### MainFrame Components

The `MainFrame` window provides the primary interface for macro operations:

```mermaid
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
```

### 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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/UpdateInfo.java#L75-L75)

---

## Configuration Files

### Configuration Overview

MouseMacros uses two JSON files for persistence:

```mermaid
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
```

### 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](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/README.md#L74-L90)

---

## Next Steps

After completing this getting started guide, explore:

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

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