msgProc: System Messages

Reference for system and utility msgProc events including container resizing, focus tracking, and clipboard operations.

Size Changed (MSG_SIZE)

MSG_SIZE fires when the container element is resized. Use this to recalculate layouts, adjust canvas dimensions, or update any size-dependent state. This event uses ResizeObserver internally and fires for both programmatic and user-driven size changes.

Message Parameters

Parameter Type Description
wParam number Resize type constant: SIZE_RESTORED (0), SIZE_MINIMIZED (1), SIZE_MAXIMIZED (2). Currently always SIZE_RESTORED in browser context
lParam number Packed dimensions: low 16 bits = width, high 16 bits = height (in pixels). Extract using LOWORD() and HIWORD()

Detail Properties

Property Type Description
width number New container width in pixels (same as LOWORD(lParam))
height number New container height in pixels (same as HIWORD(lParam))
contentRect DOMRect Full ResizeObserver content rectangle with x, y, width, height, top, right, bottom, left properties
borderBoxSize ResizeObserverSize[] Array of ResizeObserverSize objects with inlineSize and blockSize properties representing the full element dimensions including padding and border. Writing-mode aware (inline=horizontal in LTR, vertical in vertical writing modes). Use for calculations needing complete box size or for internationalization with vertical text layouts
contentBoxSize ResizeObserverSize[] Array of ResizeObserverSize objects with inlineSize and blockSize properties representing the content area dimensions excluding padding and border. Writing-mode aware. Use when sizing child elements to fit exactly within the padding, or when you need the actual drawable/usable content space
Performance Note: MSG_SIZE fires immediately during resize operations for responsive UI updates. Keep resize handlers lightweight. Only debounce expensive operations that don't need real-time feedback (heavy calculations, network requests, complex re-renders). Most resize handlers (canvas sizing, layout updates) should run immediately without debouncing.

Example: Canvas Resize

msgProc(event) {
    if (event.message === wakaPAC.MSG_SIZE) {
        const width = wakaPAC.LOWORD(event.lParam);
        const height = wakaPAC.HIWORD(event.lParam);

        // Resize canvas to match container
        this.canvasWidth = width;
        this.canvasHeight = height;

        // Recalculate layout
        this.updateLayout();

        return false;
    }
}

Copy (MSG_COPY)

MSG_COPY fires when the user initiates a copy operation (Ctrl+C, context menu copy, etc.) within the container. Use this to intercept copy operations, modify what gets placed on the clipboard, or block copying entirely.

Message Parameters

Parameter Type Description
wParam number Modifier key state at time of copy. Test with MK_SHIFT, MK_CONTROL, MK_ALT
lParam number Length of the currently selected text (0 if no text selection)

Detail Properties

Property Type Description
selectedText string The currently selected text at time of copy. Empty string if no selection
copyData object | null Mutable struct for overriding clipboard contents. Initially null. Set to an object with MIME type keys to override what gets copied (e.g., { 'text/plain': '...', 'text/html': '...' }). The framework reads this back after msgProc returns and writes it to the clipboard
Clipboard Override Pattern: MSG_COPY uses a mutable struct pattern for clipboard writes. The copyData property in event.detail starts as null. If msgProc populates it with an object, the framework prevents the default copy and writes the provided data to the clipboard instead. This works because dispatch is synchronous — msgProc runs and returns before the framework checks copyData.

Example: Override Clipboard Content

msgProc(event) {
    if (event.message === wakaPAC.MSG_COPY) {
        // Add attribution to copied text
        const text = event.detail.selectedText;

        event.detail.copyData = {
            'text/plain': text + '\n\nSource: ' + window.location.href,
            'text/html': text + '<br><small>Source: ' + window.location.href + '</small>'
        };

        return false;
    }
}

Paste (MSG_PASTE)

MSG_PASTE fires when the user initiates a paste operation (Ctrl+V, context menu paste, etc.) within the container. Use this to inspect, validate, or block incoming clipboard content before it reaches the target element. If msgProc does not cancel the paste, the content is inserted into the focused element and MSG_INPUT / MSG_INPUT_COMPLETE fire as normal.

Message Parameters

Parameter Type Description
wParam number Modifier key state at time of paste. Test with MK_SHIFT, MK_CONTROL, MK_ALT
lParam number Length of the pasted plain text (0 for non-text paste such as files)
text string Plain text content from the clipboard (text/plain). Empty string if no text data is available.
html string HTML content from the clipboard (text/html). Present when pasting from browsers, rich text editors, or applications like Word. Empty string if unavailable.
rtf string Rich Text Format content from the clipboard (text/rtf). Some applications provide RTF alongside or instead of HTML. Empty string if unavailable.
uris Array Parsed URIs from the clipboard (text/uri-list). Comments and empty lines are stripped. Present when the user copies a hyperlink or drags a URL. Empty array if unavailable.
files Array Metadata for pasted files (e.g., screenshot paste). Each entry contains name, size (bytes), and type (MIME). File blobs are accessible via originalEvent.clipboardData.files.
availableTypes Array List of all MIME types present on the clipboard. Useful for detecting application-specific formats (e.g., VS Code, Google Docs) without preemptively reading them.

Detail Properties

Property Type Description
text string Plain text content from the clipboard. Empty string if no text data is available
html string HTML content from the clipboard. Empty string if no HTML data is available. Browsers typically provide this when copying from web pages or rich text editors
files object[] Array of file metadata objects from the clipboard, each containing name (string), size (number, bytes), and type (string, MIME type). Common for screenshot pastes and image data. Empty array if no files. Access the actual File blobs via event.originalEvent.clipboardData.files if needed
Event Chain: MSG_PASTE sits upstream of the input pipeline. If the paste proceeds, the browser mutates the focused element's value, which triggers MSG_INPUT and then MSG_INPUT_COMPLETE with the updated content. Returning false from msgProc cancels the paste entirely, and no input messages fire.

Example: Validate Paste Content

msgProc(event) {
    if (event.message === wakaPAC.MSG_PASTE) {
        // Block paste if content is too long
        if (event.detail.text.length > this.maxLength) {
            this.showError('Pasted content exceeds maximum length');
            return false;
        }
    }
}

Set Focus (MSG_SETFOCUS)

MSG_SETFOCUS fires when an element within the container receives focus. Use this to track focus state, enable keyboard shortcuts, or update UI to reflect focused state.

Message Parameters

Parameter Type Description
wParam number Reserved (always 0)
lParam number Reserved (always 0)
target HTMLElement The element that received focus

Example: Enable Keyboard Shortcuts

msgProc(event) {
    if (event.message === wakaPAC.MSG_SETFOCUS) {
        this.keyboardShortcutsEnabled = true;
        return false;
    }

    if (event.message === wakaPAC.MSG_KILLFOCUS) {
        this.keyboardShortcutsEnabled = false;
        return false;
    }

    // Handle shortcuts only when focused
    if (event.message === wakaPAC.MSG_KEYDOWN && this.keyboardShortcutsEnabled) {
        if (event.wParam === wakaPAC.VK_S && (event.lParam & wakaPAC.KM_CONTROL)) {
            this.save();
            return false;
        }
    }
}

Kill Focus (MSG_KILLFOCUS)

MSG_KILLFOCUS fires when an element within the container loses focus. Use this to clean up focus-dependent state, disable keyboard shortcuts, or trigger validation.

Message Parameters

Parameter Type Description
wParam number Reserved (always 0)
lParam number Reserved (always 0)
target HTMLElement The element that lost focus

Example: Save Draft on Focus Loss

msgProc(event) {
    if (event.message === wakaPAC.MSG_KILLFOCUS) {
        // Auto-save when editor loses focus
        if (this.isDirty) {
            this.saveDraft();
        }
        return false;
    }
}

Best Practices

  • Keep resize handlers lightweight: MSG_SIZE fires frequently during resizing - avoid expensive calculations
  • Track focus state: Use MSG_SETFOCUS/KILLFOCUS to enable/disable keyboard shortcuts appropriately
  • Validate on blur: MSG_KILLFOCUS is a good trigger for field validation
  • Consider focus scope: MSG_SETFOCUS/KILLFOCUS fire for any element within the container receiving/losing focus
  • Clipboard event order: MSG_COPY and MSG_PASTE fire before any input mutation. Use them as gatekeepers to block or modify clipboard operations before they affect form elements
  • Access file blobs through originalEvent: MSG_PASTE detail contains file metadata for quick inspection. For actual file processing (upload, preview), access the File objects via event.originalEvent.clipboardData.files