bento

bento is a screen region and point/window selection tool with formattable output for both X11 and Wayland.

NOTE: The Wayland backend is still experimental and does not work correctly on multiple monitors and probably in other contexts as well, expect bugs/weird behavior

build

Building requires the zig compiler

X11 Dependencies:

• xcb
• xcb-shape
• xcb-cursor

Wayland Dependencies:

• wayland-client
• wayland-protocols
• wayland-cursor
• xkbcommon

To install, run zig build -p <prefix> where <prefix> is the directory that contains the bin folder you want it to install to.

So to install it to the system you could do:

sudo zig build -p /usr/local

and to install it for just the current user you could do:

zig build -p ~/.local

You can disable backends in the build with -Dx11-backend=false and -Dwayland-backend=false

You may also define a different build mode using -Dmode=<mode>, the default is ReleaseSmall

features

• Define a list of rectangles that can be selected by piping it in, with each line being a new rectangle

  • Format is the same as slurp, x,y wxh label (label is optional; format for the rects may change later, it's only like this now for the sake of compatibility)
  • On X11 if you don't pass in rectangles manually, then rectangles will instead be generated from the currently visible windows with labels set to the window ID. This can be disabled with the --force-no-default-rects flag

• Multiple selection modes

  • Rectangle: the standard selection mode you'd expect from any region selector
    • Modifier keys change how selection works in various ways:
      • SHIFT: Keeps the selection size constant and instead moves the whole selection region around with your mouse
      • CONTROL: Slow down the cursor to make the selection more precise
      • ALT: Lock the selection to a specific axis (whichever you move in first)
      • Additionally, if you are holding any of these modifiers when starting a selection and hovering a pre-defined rectangle, it will set the initial selection dimensions to that rectangle
  • Point: select a single pixel
  • More to come in the future (line, multi-line, multi-rectangle, whatever else might make sense)

flags/configuration

formatting

Done with the -f/--format flag or environment variables. Available formatting options for each mode:

• Rectangle
  • Environment variable: BENTO_RECTANGLE_FORMAT
  • Formatting options:
    • %x and %y: the x and y position of the top-left corner of the rectangle
    • %w and %h: the width and height of the rectangle
    • %l: the label, if selecting a pre-defined rectangle
• Point
  • Environment variable: BENTO_POINT_FORMAT
  • Formatting options:
    • %x and %y: the x and y position of the top-left corner of the rectangle
    • %l: the label, if selecting a pre-defined rectangle Additionally, escape sequences (e.g. \n, \t) will work in the format string

everything else

Selection mode is chosen with -m/--mode, defaults to rectangle if this flag is not used

You can define how much CONTROL slows down the cursor in rectangle selections with -p/--precision, given as the denominator of a fraction (e.g. -p 5 would move the cursor at 1/5th of it's normal speed), must be greater than 1

Rectangle selections can be locked into an aspect ratio with -a/--aspect, e.g. bento -a 16:9

Border size can be configured with the -s/--border-size flag or the BENTO_BORDER_SIZE environment variable

Border color (color used for selection rectangle and the currently hovered pre-defined rectangle) can be configured with the -c/--border-color flag or the BENTO_BORDER_COLOR environment variable, the value should be a hex color value, e.g. bento -c ff0000, bento --border-color "#00ffff"

Inactive border color (color used for pre-defined rectangles that aren't being hovered over) can be configured with the -i/--inactive-border-color flag or the BENTO_INACTIVE_BORDER_COLOR environment variable

The --force-no-default-rects option will disable default pre-defined rectangle generation on X11 when none are manually provided and the --force-default-rects will generate them even when you manually provide your own

On X11, if the mouse pointer is already captured by another program, bento will exit silently with an error, but if you use the --x11-wait flag, it will instead wait for the cursor to be free then continue running as normal

todo

frontend

• Abstract the code to make plugging in new modes easier
• Line selection mode
  • click and drag to draw a line between two points
  • how should formatting work? should it print two lines with details for each point, or should there be formatting options for %x2 and whatnot
    • the former would easily scale for multi-line selection (and a line selection could instead be defined as a multi-point selection, with one line being a two-point selection), the latter would be easier to parse in scripts
• Rotated rectangle mode
  • should formatting be four pairs of x,y coordinates, or should it be the normal rectangle formatting for what the rectangle would be un-rotated + an angle formatting specifier for the user to apply to those values (whichever would be simpler for cropping a screenshot to a rotated rectangle, research this more)
    • or maybe i could just do both, %x, %y, %w, %h, and %a alongside %p1x, %p1y, etc.
• Mode that only lets you select pre-defined rectangles
  • formatting would give you everything rectangle formatting does

backend

• Provide a way for backends to dynamically update the rectangles they provide, this will allow the X11 backend to fully simulate the behavior of traditional region selection tools that are directly aware of windows

• wayland

  • Multi-monitor support
    • i only have one monitor, which makes this hard to develop properly
  • More efficient line drawing algorithm
    • not too important, won't really matter until diagonal line rendering is necessary

• x11

  • Don't generate rectangles for windows that are completely covered by other windows
  • Rewrite using xzb

build

• Auto-detect which backends have their dependencies satisfied and build with just those when not manually specified
• Instead of flags like -Dx11-backend=BOOL, their should be one flag that takes a list of backends (e.g. -Dbackends=x11,wayland)

other less organized notes and plans that may or may not happen

• flag to restrict selections to a specific region (boox had this, but I think I can't really think of any use case to justify it's existence)
• ability to pass in the starting coordinate for a selection
• stamp mode: you pass in the size of the rectangle then place in somewhere on the screen
• slop flags
  • tolerance seems marginally useful
  • i can't think of a good use case for padding, if this is something you would care about let me know
  • nodrag seems useful as an accessibility option, but accessibility tools might already have similar functionality, if you have knowledge on this please let me know
  • research nodecorations more, i don't have window decorations so i need to find a good environment to test and explore how it works
• alternative entry point into bento as a library, so it can be embedded into things like window managers and return results as native values instead of printing them
  • this should definitely be possible through other zig code if i do this, might also make it so bento can be built as a C-compatible library
• arcan backend? unsure how feasible this is, but arcan is a cool project and i'd like to contribute to it's ecosystem
  • if i do it, won't be until after the wayland backend is finished