winclip

Read and write the Windows clipboard from Ruby: text, images, and file lists.

winclip is a native Windows clipboard library. It gets and sets:

  • text — Unicode, as UTF-8 Strings;
  • images — as PNG bytes (converted to/from CF_DIB/CF_DIBV5 via WIC);
  • file lists — as arrays of paths (CF_HDROP).

The PNG image interface pairs directly with windraw — draw something and drop it on the clipboard, or grab a copied screenshot and save it.

Requirements

  • Windows with a native MSVC (mswin) Ruby (x64-mswin64). Not supported on MinGW/UCRT Ruby (the extconf.rb will say so).
  • Visual Studio 2017+ / Build Tools with the Desktop development with C++ workload. Building uses vcvars to load the toolchain automatically — no Developer Command Prompt needed.

Install

gem install winclip

Usage

require "winclip"

# --- text ---
Winclip.text = "héllo ✓ 日本"
Winclip.text            # => "héllo ✓ 日本"  (UTF-8)
Winclip.copy("quick")   # alias for text=
Winclip.paste           # alias for text

# --- images (PNG bytes) ---
Winclip.image = File.binread("logo.png")
File.binwrite("pasted.png", Winclip.image) if Winclip.has_image?

# straight from windraw:
require "windraw"
Winclip.image = Windraw.surface(200, 80) { |c| c.clear("#1e1e2e"); c.text("hi", 10, 20, color: "#fff") }.to_png

# --- file lists ---
Winclip.files = ["C:/a.txt", "C:/b.txt"]   # also accepts a single path String
Winclip.files                              # => ["C:/a.txt", "C:/b.txt"]

# --- queries & management ---
Winclip.has_text?       # => true / false
Winclip.has_image?      # => true / false
Winclip.has_files?      # => true / false
Winclip.formats         # => ["CF_UNICODETEXT", "CF_TEXT", "CF_LOCALE", ...]
Winclip.available?(:image)            # => true / false
Winclip.available?("PNG")             # registered format by name
Winclip.available?("CF_HDROP")        # standard format by name
Winclip.clear           # empty the clipboard

All getters return nil when that kind of content isn't on the clipboard, so you can write Winclip.text or abort "nothing copied".

Notes

  • Images are exchanged as PNG bytes (binary ASCII-8BIT Strings). On set, winclip publishes both CF_DIBV5 (alpha-aware) and CF_DIB for the widest app compatibility; on get it reads CF_DIBV5/CF_DIB (24- or 32-bit) and encodes PNG. Palette (1/4/8-bit) DIBs are not decoded.
  • Clipboard work happens on the calling thread; do clipboard operations from one thread.

License

MIT.