# kallunwillock/ezpzmousecontroller architecture

> Architecture diagram of the GitHub repository kallunwillock/ezpzmousecontroller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kallunwillock/ezpzmousecontroller
- Repository: https://github.com/kallunwillock/ezpzmousecontroller

## Overview

##### Project type and purpose
- This is a VBA-based library (with a demo Excel workbook) for capturing MouseWheel and other mouse events in UserForms and controls, using the Microsoft Tablet PC InkCollector COM object instead of subclassing or Win32 API calls.
- The demo workbook (`EZPZMouseController_Demo.xlsm`) shows how to integrate and exercise the library, and the `src` folder contains the actual VBA code (UserForm definitions and modules).

##### File structure
- Top‐level files:
- EZPZMouseController_Demo.xlsm – the Excel/VBA demo
- LICENSE, README.md – project metadata
- src/ – the VBA source code tree
- Inside `src/`:
- frmMouse_Wheel.frm (+ .frx) – a UserForm demonstrating wheel capture
- frmMouse_Windowless.frm (+ .frx) – a UserForm showing “windowless” capture technique
- modMisc.bas – utility routines (e.g., reference‐adding function)
- modTaskBox.bas – routines for UI tasks (e.g., grouping controls, dynamic binding)
- No build scripts or external deployment; simply import into an Excel VBA project.

##### Key insights from the README
- Core dependency: Microsoft Tablet PC Type Library (InkObj.dll)
- Architecture: VBA UserForms ↔ InkCollector COM objects ↔ Windows mouse event stream
- Demo code illustrating initialization, event‐interest settings, and handler implementations.

a. Main components:
1. Excel Host Application
2. VBA Project Container
‑ UserForms (frmMouse_Wheel, frmMouse_Windowless)
‑ Code Modules (modMisc, modTaskBox)
3. InkCollector COM Object (from Microsoft Tablet PC Type Library)
4. Windows OS Input Subsystem (raw mouse events)
5. Developer/User Code (event handlers inside UserForms)
b. Relationships & Data Flow:
- The Windows OS generates mouse events → InkCollector (registered as a COM event sink)
- InkCollector raises VBA events (`IC_MouseWheel`, `IC_MouseDown`, etc.)
- VBA event handlers in the UserForm modules receive event arguments (Delta, X, Y, Shift)
- Handlers invoke code in modTaskBox or modMisc to perform scrolling, UI updates, or repositioning controls
c. Architectural patterns & principles:
- Event‐driven pattern (InkCollector events callback into VBA handlers)
- Separation of demonstration (UserForms) vs. utility code (modules)
- Dependency injection by setting `IC.hWnd` at runtime to attach to specific control windows
d. Key technologies:
- VBA UserForms (.frm/.frx)
- COM interop via InkCollector (MSINKAUTLib)
- Excel VBA host

##### Detail level & essential elements
- UserForm separately, showing the `WithEvents IC As InkCollector` declaration.
- ModMisc’s `AddMSInkReference` as the setup step.
- Fact that multiple InkCollector instances can be bound to different hWnds (frame controls vs. whole form).
- Don’t over‐partition: group similar modules together, but call out distinctive responsibilities (event binding vs. UI logic).

– The layering (Windows → COM → VBA → Excel UI)
– The separation of library vs. demo code
– The key flow of mouse events from OS to your VBA handlers
– How a consumer would integrate and extend the library in their own VBA projects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Project Files
    subgraph "Project Files"
        Excel["Excel Host Application<br/>(EZPZMouseController_Demo.xlsm)"]:::host
        License["LICENSE"]:::external
        Readme["README.md"]:::external
        SRC["VBA Source Container (src/)"]:::internal
    end

    %% VBA Project Contents
    subgraph "VBA Project Container"
        subgraph "Demo Code"
            WF["UserForm: frmMouse_Wheel"]:::internal
            WL["UserForm: frmMouse_Windowless"]:::internal
        end
        subgraph "Library Modules"
            MMC["Module: modMisc.bas"]:::library
            MTB["Module: modTaskBox.bas"]:::library
        end
    end

    %% External & Host Components
    OS["Windows OS Input Subsystem"]:::host
    Ink["InkCollector COM Object<br/>(MSINKAUTLib)"]:::external

    %% Connections
    OS -->|"Raw mouse events"| Ink
    Ink -->|"IC_MouseXXX event callbacks"| WF
    Ink -->|"IC_MouseXXX event callbacks"| WL
    WF -->|"Invokes helpers"| MMC
    WF -->|"Invokes UI routines"| MTB
    WL -->|"Invokes helpers"| MMC
    WL -->|"Invokes UI routines"| MTB
    MMC -->|"AddMSInkReference (setup)"| Ink
    MTB -->|"Control repositioning/UI updates"| Excel
    Excel -->|"Hosts VBA Project"| WF
    Excel -->|"Hosts VBA Project"| WL

    %% Click Events
    click Excel "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/EZPZMouseController_Demo.xlsm"
    click License "https://github.com/kallunwillock/ezpzmousecontroller/tree/main/LICENSE"
    click Readme "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/README.md"
    click SRC "https://github.com/kallunwillock/ezpzmousecontroller/tree/main/src/"
    click WF "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/src/frmMouse_Wheel.frm"
    click WL "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/src/frmMouse_Windowless.frm"
    click MMC "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/src/modMisc.bas"
    click MTB "https://github.com/kallunwillock/ezpzmousecontroller/blob/main/src/modTaskBox.bas"

    %% Styles
    classDef host fill:#ccc,stroke:#333,color:#000;
    classDef external fill:#cfc,stroke:#090,color:#000;
    classDef internal fill:#ccf,stroke:#00f,color:#000;
    classDef library fill:#cce,stroke:#00a,color:#000;
```
