multimon

README

go-multimon

A Go package for handling window positioning and sizing across multiple monitors. Provides utilities for fitting windows to monitors while respecting work areas (taskbars/docks) and handling various edge cases.

Features

• Monitor-aware window positioning and sizing
• Support for work areas (excluding taskbars/docks)
• Intelligent window fitting based on:
  • Overlap area with monitors
  • Edge distance when no overlap exists
  • Minimum size requirements
• Initial window placement with:
  • Margin support with minimum size guarantees
  • Automatic centering in work area
• Cross-platform support (Windows, Linux, macOS)
• Handles various edge cases:
  • Windows spanning multiple monitors
  • Windows outside all monitors
  • Zero or negative size windows
  • Windows larger than monitor bounds

Installation

go get github.com/adnsv/multimon

This package has no external Go dependencies - it only uses the standard library and CGO bindings to system libraries.

Platform Support

• Windows: Native support via Win32 API (pure Go)
• macOS: Support via Cocoa/AppKit (requires cgo)
• Linux: Support via GTK3/GDK (requires cgo, gtk3-dev package)

Each platform implementation provides:

• Monitor enumeration
• Physical and logical monitor bounds
• Work area detection (accounting for taskbars/docks)

Dependencies

For non-Windows platforms, this package requires CGO and the appropriate development packages:

• Linux: gtk3-dev (or libgtk-3-dev on Debian/Ubuntu)
• macOS: Xcode Command Line Tools (provides Foundation, Cocoa, and AppKit frameworks)

  xcode-select --install
  

Usage

Initial Window Placement

// Get initial window placement on default monitor (containing 0,0 or largest)
rect := multimon.InitialPlacement(
    minWidth,    // minimum required width
    minHeight,   // minimum required height
    desiredWidth,    // preferred width
    desiredHeight,   // preferred height
    margin,      // minimum distance from work area edges
)
// rect contains window position centered in work area

All coordinates and dimensions are in logical (scaled) pixels, accounting for system DPI settings.

Documentation

Index

• Variables
• func ContainsLogicalPoint(m Monitor, x, y int) bool
• func ContainsPhysicalPoint(m Monitor, x, y int) bool
• type FitMode
• type Monitor
  • func FindMonitorFromLogicalPoint(monitors []Monitor, x, y int) *Monitor
  • func FindMonitorFromLogicalRect(monitors []Monitor, rect Rect) *Monitor
  • func FindMonitorFromPhysicalPoint(monitors []Monitor, x, y int) *Monitor
  • func GetMonitors() []Monitor
• type Rect
  • func FitToMonitor(m Monitor, mode FitMode, window Rect) (Rect, error)
  • func FitToNearestMonitor(monitors []Monitor, mode FitMode, window Rect, minWidth, minHeight int) (Rect, error)
  • func InitialPlacement(minWidth, minHeight, desiredWidth, desiredHeight, margin int) Rect
  • func LogicalToPhysical(m Monitor, logical Rect) Rect
  • func PhysicalToLogical(m Monitor, physical Rect) Rect

Variables

var ErrInvalidDimensions = errors.New("invalid dimensions: negative width or height")

ErrInvalidDimensions is returned when a window or monitor has negative dimensions

var ErrNoMonitors = errors.New("no monitors available")

ErrNoMonitors is returned when no monitors are available for fitting

Functions

func ContainsLogicalPoint

func ContainsLogicalPoint(m Monitor, x, y int) bool

ContainsLogicalPoint checks if a logical point is within the monitor's logical bounds

func ContainsPhysicalPoint

func ContainsPhysicalPoint(m Monitor, x, y int) bool

ContainsPhysicalPoint checks if a physical point is within the monitor's physical bounds

Types

type FitMode

type FitMode int

FitMode specifies how to fit a window to a monitor

const (
	// FitModeBounds fits to monitor's total bounds
	FitModeBounds FitMode = iota
	// FitModeWorkArea fits to monitor's work area (excluding taskbar, dock, etc.)
	FitModeWorkArea
)

type Monitor

type Monitor = types.Monitor

Monitor represents a display monitor and its properties

func FindMonitorFromLogicalPoint

func FindMonitorFromLogicalPoint(monitors []Monitor, x, y int) *Monitor

FindMonitorFromLogicalPoint finds the monitor that contains the given logical point

func FindMonitorFromLogicalRect

func FindMonitorFromLogicalRect(monitors []Monitor, rect Rect) *Monitor

FindMonitorFromLogicalRect finds a monitor with the largest overlap with the given rect

func FindMonitorFromPhysicalPoint

func FindMonitorFromPhysicalPoint(monitors []Monitor, x, y int) *Monitor

FindMonitorFromPhysicalPoint finds the monitor that contains the given physical point

func GetMonitors

func GetMonitors() []Monitor

GetMonitors returns monitor information

type Rect

type Rect = types.Rect

Rect represents a rectangle with coordinates in screen space

func FitToMonitor

func FitToMonitor(m Monitor, mode FitMode, window Rect) (Rect, error)

FitToMonitor fits a window to a specific monitor. All coordinates are in logical space. Returns error if window or monitor has negative dimensions.

func FitToNearestMonitor

func FitToNearestMonitor(monitors []Monitor, mode FitMode, window Rect, minWidth, minHeight int) (Rect, error)

FitToNearestMonitor finds the most appropriate monitor and fits the window to it. If minWidth and minHeight are > 0, it will try to find a monitor that can fit these minimum dimensions. Returns error if window has negative dimensions or if no valid monitors are available.

func InitialPlacement

func InitialPlacement(minWidth, minHeight, desiredWidth, desiredHeight, margin int) Rect

InitialPlacement calculates the initial window placement on a default monitor. The default monitor is either: - The monitor containing point (0,0) in logical coordinates - If no monitor contains (0,0), the monitor with largest logical area

All calculations are performed in logical (scaled) coordinates, accounting for the system's DPI settings and scaling factors.

Parameters: - minWidth, minHeight: minimum required window size in logical pixels - desiredWidth, desiredHeight: preferred window size in logical pixels (will be clamped if exceeds work area) - margin: minimum distance from work area edges in logical pixels

Returns a Rect with the calculated window position and size in logical coordinates.

func LogicalToPhysical

func LogicalToPhysical(m Monitor, logical Rect) Rect

LogicalToPhysical converts logical coordinates to physical coordinates for a given monitor

func PhysicalToLogical

func PhysicalToLogical(m Monitor, physical Rect) Rect

PhysicalToLogical converts physical coordinates to logical coordinates for a given monitor