GPM

Crystal-native client for GPM (console mouse).

NOTE: This library will only work when a program is running in the console and GPM server is running. One needs to be on a TTY and executing the command tty should report something like tty<NUMBER>. It won't work under X and pseudoterminals (ptys, pts's) where running tty reports something like /dev/pts/<NUMBER>.

GPM is a simple protocol where we connect to the gpm's unix socket and listen for events. Each event gives us the following information:

buttons : Buttons (right, middle, left, fourth, up, down)
modifiers : Keyboard modifiers (shift, control, meta)
dx : Delta (change) of x
dy : Delta (change) of y
x : Absolute x
y : Absolute y
types : Types of event (move, drag, down, up, single, double, triple, motion)
clicks : Number of clicks counted
margins : Which screen margins were touched (top, bottom, left, right)
wdx : Delta (change) of mouse wheel, horizontal
wdy : Delta (change) of mouse wheel, vertical

We can also request information from GPM. This is done by writing the config structure into the socket, in which the process PID field is set to 0 and the vc (virtual console) number field is set to the number/ID of request. There are 4 requests available in enum Request: snapshot, buttons, config, nopaste.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     gpm:
       github: crystallabs/gpm.cr
       version: ~> 1.0
   

2. Run shards install

Usage

require "gpm"

gpm = GPM.new
while e = gpm.get_event
  p e
end

Example output:

$ crystal examples/gpm.cr

GPM::Event(@buttons=None, @modifiers=None, @vc=6, @dx=0, @dy=0, @x=163, @y=35, @type=MOVE, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=LEFT, @modifiers=None, @vc=6, @dx=0, @dy=0, @x=163, @y=35, @type=DOWN | SINGLE, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=LEFT, @modifiers=None, @vc=6, @dx=0, @dy=0, @x=163, @y=35, @type=UP | SINGLE, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=RIGHT, @modifiers=None, @vc=6, @dx=0, @dy=0, @x=163, @y=35, @type=DOWN | SINGLE, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=RIGHT, @modifiers=CTRL, @vc=6, @dx=0, @dy=0, @x=163, @y=35, @type=DRAG | SINGLE | MOTION, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=RIGHT, @modifiers=CTRL, @vc=6, @dx=1, @dy=0, @x=164, @y=35, @type=DRAG | SINGLE | MOTION, @clicks=0, @margins=None, @wdx=0, @wdy=0)
GPM::Event(@buttons=RIGHT, @modifiers=CTRL, @vc=6, @dx=0, @dy=0, @x=164, @y=35, @type=UP | SINGLE | MOTION, @clicks=0, @margins=None, @wdx=0, @wdy=0)

Thanks

• All the fine folks on Libera.Chat IRC channel #crystal-lang and on Crystal's Gitter channel https://gitter.im/crystal-lang/crystal

Licensing

For licensing to use in your next project, consider Coherent or Post-Open Source licenses:

• https://licenseuse.org/
• https://www.youtube.com/watch?v=vTsc1m78BUk
• https://www.youtube.com/watch?v=XRl-it1-ruI
• https://perens.com/2020/10/06/post-open-source-license-early-draft/