# Custom UI Components

> **Relevant source files**
> * [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java)

## Purpose and Scope

This document describes custom Swing components created for the MouseMacros application that extend or enhance standard Java Swing widgets. These components provide specialized functionality beyond what standard Swing offers, including enhanced styling, dynamic sizing behavior, and integration with the application's theming system (see [Theming and UI Styling](Custom-UI-Components)).

Currently, the application includes one primary custom component: `CustomToolTipWindow`, which provides styled tooltip windows with intelligent text wrapping and theme-aware rendering.

## CustomToolTipWindow

The `CustomToolTipWindow` class provides an enhanced tooltip display system that replaces standard Swing tooltips with a custom `JWindow` implementation featuring rounded corners, border styling, and dynamic text layout.

### Class Overview

`CustomToolTipWindow` extends `JWindow` to create a lightweight, always-on-top window that displays tooltip text. Unlike standard tooltips, this implementation provides:

* Rounded corner rendering with anti-aliasing
* Integration with the application's dark/light mode system
* Intelligent text wrapping based on screen size or fixed width constraints
* HTML-based text formatting with center alignment
* Configurable width behavior via the `allowLongStr` parameter

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L11-L19](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L11-L19)

### Component Architecture

```mermaid
classDiagram
    class CustomToolTipWindow {
        -JLabel label
        -boolean allowLongStr
        -int FIXED_WIDTH
        +CustomToolTipWindow(String text, boolean allowLongStr)
        +setText(String text)
    }
    class JWindow {
        «Java Swing»
    }
    class JPanel {
        «Java Swing»
        +paintComponent(Graphics g)
    }
    class JLabel {
        «Java Swing»
    }
    class ConfigManager {
        +Config config
    }
    class ComponentUtil {
        +setMode(Component, int)
    }
    class SystemUtil {
        +getScale() : double[]
    }
    JWindow <|-- CustomToolTipWindow : contains
    CustomToolTipWindow --> JPanel : contains label
    CustomToolTipWindow --> JLabel : reads theme
    CustomToolTipWindow --> ConfigManager : applies styling
    CustomToolTipWindow --> ComponentUtil : scales dimensions
    CustomToolTipWindow --> SystemUtil
```

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L1-L68](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L1-L68)

### Constructor and Initialization

The constructor performs a multi-step initialization sequence:

| Step | Action | Line Reference |
| --- | --- | --- |
| 1 | Set always-on-top property | [CustomToolTipWindow.java L20](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L20-L20) |
| 2 | Create custom JPanel with rounded corner rendering | [CustomToolTipWindow.java L21-L32](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L21-L32) |
| 3 | Configure JLabel with padding and alignment | [CustomToolTipWindow.java L34-L37](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L34-L37) |
| 4 | Apply border styling | [CustomToolTipWindow.java L40](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L40-L40) |
| 5 | Detect and apply theme mode (dark/light) | [CustomToolTipWindow.java L43-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L43-L44) |
| 6 | Set initial text content | [CustomToolTipWindow.java L45](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L45-L45) |

The `FIXED_WIDTH` constant is computed at construction time by scaling a base value of 130 pixels according to the system's display scale factor: `(int)(130 * SystemUtil.getScale()[0])`.

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L17-L46](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L17-L46)

### Rounded Corner Rendering

The custom `JPanel` overrides `paintComponent()` to render rounded corners using Java2D graphics:

```mermaid
sequenceDiagram
  participant JPanel
  participant Graphics2D
  participant Background

  JPanel->>JPanel: paintComponent(Graphics g)
  JPanel->>Graphics2D: create()
  JPanel->>Graphics2D: setRenderingHint(ANTIALIASING, ON)
  JPanel->>Graphics2D: setColor(getBackground())
  JPanel->>Graphics2D: fillRoundRect(0, 0, width, height, 12, 12)
  JPanel->>Graphics2D: dispose()
```

The implementation uses:

* Anti-aliasing for smooth edges
* 12-pixel corner radius (both horizontal and vertical)
* Background color from theme system
* Double buffering inherited from `JPanel`

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L23-L31](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L23-L31)

### Text Layout and Wrapping

The `setText()` method implements intelligent text wrapping with two distinct behaviors controlled by the `allowLongStr` parameter:

#### Text Layout Decision Flow

```

```

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L47-L67](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L47-L67)

#### Layout Modes

| Mode | Trigger | Maximum Width | Use Case |
| --- | --- | --- | --- |
| Long String Mode | `allowLongStr = true` | 80% of screen width | Verbose tooltips, multi-line descriptions |
| Fixed Width Mode | `allowLongStr = false` | `FIXED_WIDTH` (130px scaled) | Short tooltips, compact UI |

The width calculation in fixed mode applies a 0.8 multiplier to the label width before comparison: `labelWidth * 0.8 > FIXED_WIDTH`. This provides a buffer zone to prevent wrapping for text that only slightly exceeds the limit.

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L52-L66](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L52-L66)

### HTML Text Formatting

All text is rendered using HTML to support:

* Multi-line display via `<br>` tags (converted from `\n` characters)
* Center alignment via inline CSS
* Dynamic width constraints via inline CSS `width` property
* Proper text wrapping within constrained areas

Example HTML structure:

```html
<html><div style='text-align:center;'>Line 1<br>Line 2</div></html>
```

When width limits are applied:

```html
<html><div style='width: 500px; text-align:center;'>Long text...</div></html>
```

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L48-L58](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L48-L58)

### Theme Integration

The component integrates with the application's theme system through these mechanisms:

```

```

The theme is applied once during construction at [CustomToolTipWindow.java L43-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/CustomToolTipWindow.java#L43-L44)

 The `ComponentUtil.setMode()` method recursively applies the selected color scheme to the panel and its child label, ensuring consistent appearance with the rest of the application (see [ComponentUtil](Component-Utilities) for details).

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L3-L44](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L3-L44)

### Component Hierarchy

The internal component structure:

```

```

This hierarchy creates a layered appearance:

1. Window provides positioning and always-on-top behavior
2. Panel provides rounded background via custom painting
3. Border provides visual edge definition
4. Label provides text content with internal padding

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L21-L41](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L21-L41)

### Display Properties

Key display characteristics:

| Property | Value | Purpose |
| --- | --- | --- |
| Always on Top | `true` | Ensures tooltip visibility over all windows |
| Panel Opacity | `false` | Allows rounded corner transparency |
| Border Radius | 12px | Rounded corner radius for all four corners |
| Border Color | RGB(180, 180, 180) | Light gray outline |
| Border Width | 1px | Subtle edge definition |
| Label Padding | 6px top/bottom, 12px left/right | Internal spacing |
| Base Width | 130px | Fixed width baseline (scaled by DPI) |

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L15-L40](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L15-L40)

## Usage Patterns

While the provided source file does not include usage examples, `CustomToolTipWindow` instances would typically be created and displayed in response to UI events where enhanced tooltip information is needed. The component's flexibility in handling both short and long text makes it suitable for various contexts throughout the application.

The two-parameter constructor allows calling code to specify both the content and the layout mode:

* Use `allowLongStr = true` for verbose informational tooltips
* Use `allowLongStr = false` for compact, quick-reference tooltips

**Sources:** [src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java L17-L19](https://github.com/Samera2022/MouseMacros/blob/1eb6620b/src/io/github/samera2022/mouse_macros/ui/component/CustomToolTipWindow.java#L17-L19)