monitor-utils
is a Rust library and binary for making geometric/spatial queries on monitors.
It provides functionality for working with monitors and their configurations.
This README provides an overview of the library's public API, cargo features, and information about the CLI.
The monitor-utils
CLI has a unique interface for interacting with the library.
It allows you to perform various actions and chain them together using a pipeline-like syntax.
CLI for monitor-utils
Usage: [-s] [-r] [--at-point <X> <Y> | (--clockwise | --counter-clockwise | --center |
--geometry)]...
Available options:
-s, --shell If specified, spit out output in POSIX shell variable format, such that it may
be eval'd
-r, --refresh If specified, refreshes the cache before running actions
The following options are commands, which pipeline data from the left of the command-line to the
right.
--at-point <X> <Y>
Takes 2 arguments: X and Y, and yields the monitor containing the point (X,Y)
--at-point
These commands each take in a Monitor through the pipeline, and yield either a Point or another
Monitor.
--clockwise Given an argument monitor, yields the next monitor in a clockwise rotation.
--counter-clockwise Given an argument monitor, yields the next monitor in a
counter-clockwise rotation.
--center Given an argument monitor, yields the point at the center of the monitor.
--geometry Given an argument monitor, yields the geometry of the monitor.
-h, --help Prints help information
-V, --version Prints version information
$ monitor-utils --at-point 800 1600 --clockwise --center
Point { x: 3840, y: 1080 }
$ monitor-utils --shell --at-point 800 1600 --clockwise --center
X=3840
Y=1080
$ monitor-utils --shell --at-point 800 1600 --clockwise --geometry
X_OFFSET=1920
Y_OFFSET=0
WIDTH=3840
HEIGHT=2160
The monitor-utils
CLI can be used in conjunction with xdotool
to perform actions based on monitor configurations.
For example, you can use it to move your cursor to the center of the next monitor.
# Get the X and Y coordinates of the mouse
eval $(xdotool getmouselocation)
# Get the X and Y coordinates of the center of the next monitor
eval $(monitor-utils --at-point $X $Y --clockwise --center)
# Move the mouse to the center of the next monitor
xdotool mousemove $X $Y
default
: By default, only thex11
feature is enabled.x11
: Enables thex11
module, which contains aLoadMonitors
implementation usingXRandr
.serialize
: Usesminiserde
to serialize/deserializeMonitorSetup
.global-cache
: Usesserialize
to read/write setup from a global cache.cli
: Enables compilation of the binary:bin/monitor-utils
.
Represents a rectangle lying on a virtual screen.
center() -> Point
: Returns the point at the center of theRect
.- this can be used in conjunction with
Monitor
to get the point at the center of aMonitor
- this can be used in conjunction with
A trait that abstracts loading the list of monitors from the respective environment. By implementing this trait, you can use the library's functionality for arbitrary windowing systems.
load_monitors() -> Result<Vec<Monitor>, E>
: Loads the list of monitors and returns a vector ofMonitor
instances. Generic over the Error type.
Represents a group of monitors used in conjunction with one another.
-
with_loader(loader: impl LoadMonitors<E>) -> Result<MonitorSetup, E>
: Creates aMonitorSetup
instance using the providedLoadMonitors
implementation. -
reload(loader: impl LoadMonitors<E>) -> Result<(), E>
: Reloads the monitor setup using the providedLoadMonitors
implementation. -
from_json(json_string: &str) -> Result<Self>
: (serialize
feature) Creates aMonitorSetup
instance by deserializing from a JSON string. -
from_global_cache() -> Result<Self>
: (global-cache
feature) Creates aMonitorSetup
instance by reading from the global cache. -
to_global_cache() -> Result<()>
: (global-cache
feature) Writes theMonitorSetup
instance to the global cache. -
monitor_containing_point(point: &Point) -> Result<&Monitor>
: Returns the monitor that contains the given point. -
next_monitor_clockwise(monitor: &Monitor) -> Result<&Monitor>
: Returns the next monitor in a clockwise traversal of theMonitorSetup
. -
next_monitor_counterclockwise(monitor: &Monitor) -> Result<&Monitor>
: Returns the next monitor in a counterclockwise traversal of theMonitorSetup
. -
TODO:
monitor_above(monitor: &Monitor) -> Result<&Monitor>
: Returns the monitor above the given monitor. -
TODO:
monitor_below(monitor: &Monitor) -> Result<&Monitor>
: Returns the monitor below the given monitor. -
TODO:
monitor_left_of(monitor: &Monitor) -> Result<&Monitor>
: Returns the monitor to the left of the given monitor. -
TODO:
monitor_right_of(monitor: &Monitor) -> Result<&Monitor>
: Returns the monitor to the right of the given monitor.
This project is licensed under the MIT License. See the LICENSE file for details.