xpaint.1

.TH XPAINT 1 xpaint VERSION "Modal Image Editor"

.SH NAME
xpaint \- a lightweight modal X11 image editor

.SH SYNOPSIS
.B xpaint
[\fIOPTIONS\fP] [\fIFILE\fP]

.SH DESCRIPTION
xpaint is a lightweight modal image editor combining keyboard-driven efficiency with precision drawing tools. Its hybrid interface supports pixel-perfect editing, infinite undo/redo, and contextual radial menus for quick color/tool selection, ideal for technical diagrams and quick sketches.

.SH POSITIONAL ARGUMENTS
.TP 12
\fI\fUFILE\fP
Specifies the path or URI of the image file to be edited. The commands \fBSave\fP and \fBload\fP will refer to this file. Use "-" to read from standard input and write to standard output. This may be overridden by the \fI\-\-input\fP and \fI\-\-output\fP options.

.SH OPTIONS
.TP
.B \-h, \-\-help
Print help message.
.TP
.B \-V, \-\-version
Print version.
.TP
.B \-v, \-\-verbose
Enable verbose output.
.TP
.B \-W \fIWIDTH\fP, \-\-width \fIWIDTH\fP
Set the canvas width (default: 1000).
.TP
.B \-H \fIHEIGHT\fP, \-\-height \fIHEIGHT\fP
Set the canvas height (default: 700).
.TP
.B \-i \fIFILE\fP, \-\-input \fIFILE\fP
Specify the input file to load.
.TP
.B \-o \fIFILE\fP, \-\-output \fIFILE\fP
Specify the output file for saving.

.SH USAGE

.SS MODES
xpaint supports several modes:
.IP "\fIINTERACT\fP (INT)"
(Default mode) for direct canvas editing. Press \fB<Esc>\fP to switch modes.
.IP "\fICOLOR\fP (COL)"
For modifying the color in the current tool context. Enter by pressing \fBc\fP.
.IP "\fICONSOLE\fP (CMD)"
For executing text-based commands. Enter by pressing \fB:\fP.
.IP "\fITRANSFORM\fP (TFM)"
Automatically entered when using the selection tool, allowing image scaling, moving, and rotation.
.IP "\fITEXT\fP (TXT)"
Automatically entered when using the text tool, type text to draw on canvas.

.SH CONSOLE
In console mode, all keystrokes are directed to the command line. Auto-completion is available by default.
.TP
.B echo \fI\fUMESSAGE\fP
Display a message in the status line.
.TP
.B set \fI\fUPROPERTY\fP \fI\fUVALUE\fP
Set a given property to a new value.
Available properties include:
.RS
.RS
.IP "line_w"
The width of drawing tools.
.IP "col"
The current tool context color in hex format (e.g. 00A283).
.IP "font"
The interface font, provided as an Xft name.
.IP "inp"
The input file (use "-" for stdin).
.IP "out"
The output file (use "-" for stdout).
.IP "png_cmpr"
PNG compression level.
.IP "jpg_qlty"
JPG quality level.
.IP "spacing"
Brush spacing for drawing.
.RE
.RE
.TP
.B q
Exit the program without saving.
.TP
.B w
Save changes to opened file.
.TP
.B wq
Save changes to opened file and exit program.
.TP
.B save \fI\fUTYPE\fP [\fIFILE\fP]
Save the canvas contents to a file as a PNG or JPG. If \fIFILE\fP is omitted, the current output path is used.
.TP
.B load [\fIFILE\fP]
Load the specified file onto the canvas. If omitted, the current input path is used.

.SH TOOL CONTEXT
The tool context holds the active tool and the palette of colors. Available tool contexts are displayed in the lower left corner of the status bar. Change the active tool using the number keys. Only one tool is active at any moment (default is the pencil).

.SH TOOLS
The following tools are available for canvas editing:
.TP
.B PENCIL
Draws squares and lines using the left mouse button; hold \fBShift\fP to use the previous point as the start of a new line.
.TP
.B BRUSH
Similar to the pencil but produces smoother, rounded strokes. Spacing adjustments are available.
.TP
.B SELECTION
Selects rectangular areas and switches to transform mode. Drag to move or clone the selection (use \fBShift\fP for cloning) and copy to the X selection with \fBC-c\fP. Use \fBEsc\fP to exit transform mode and apply changes.
.TP
.B FILL
Fills closed regions with the current color.
.TP
.B PICKER
Extracts a color from the canvas.
.TP
.B FIGURE
Draws regular shapes (circle, square, triangle). The current figure type can be changed through the selection circle.
.TP
.B TEXT
Use to initiate text mode by selecting the bottom-left corner where the text will be drawn.

.SH KEYBOARD COMMANDS
The following key bindings are active by default. (All keys can be reconfigured in \fIconfig.h\fP.)
.TP
.B ACT_MODE_INTERACT \fB<Esc>\fP
Switch to interact mode. Cancel completions in console mode.
.TP
.B ACT_EXIT \fBq\fP
Exit xpaint.
.TP
.B ACT_SAVE_TO_FILE \fB<C-s>\fP
Save canvas to output path.
Output path can be passed via \fI\-\-output\fP argument,
\fIFILE\fP positional argument, or via console.
Saved image type same as currently loaded file (PNG if no file loaded).
.TP
.B ACT_UNDO <C-z>
Undo the most recent action.
.TP
.B ACT_REVERT <C-Z>
Redo the most recently undone action.
.TP
.B ACT_COPY_AREA <C-c>
Capture the selected area (as image/png) for copying.
.TP
.B ACT_PASTE_IMAGE <C-v>
Paste the clipboard image (automatically switches to transform mode).
.TP
.B ACT_SWAP_COLOR x
Swap the current drawing color with the previous color.
.TP
.B (no action) NUMBER (0 to 9)
Switch between available tool contexts.
.TP
.B (no action) <C-Left>, <C-Right>, <C-Down>, <C-Up>
Resize the canvas (hold shift to increase step).
.TP
.B ACT_ZOOM_IN / ACT_ZOOM_OUT <C-plus>/<C-minus>
Zoom in and out of the canvas.
.TP
.B ACT_MODE_COLOR c
Switch to color mode.
.TP
.B ACT_ADD_COLOR <C-Up>
In color mode. Extend the number of colors in the current tool context.
.TP
.B ACT_TO_RIGHT_COL_DIGIT / ACT_TO_LEFT_COL_DIGIT <Right>/<Left>
In color mode. Move cursor to next or previous digit in modified color.
.TP
.B (no action) Number keys (0-F)
In color mode. Change selected digit to typed.
.TP
.B ACT_MODE_CONSOLE \fB:\fP
Switch to console mode.
.TP
.B (no action) LETTER (except ACT_MODE_INTERACT)
In console mode. Append letter to command.
.TP
.B KEY_CL_NEXT_COMPLT <Tab>
In console mode. Cycle completions.
.TP
.B KEY_CL_APPLY_COMPLT <Return>
In console mode. Apply completions.
.TP
.B KEY_CL_RUN <Enter>
In console mode. Run the command.
.TP
.B KEY_CL_CLIPBOARD_PASTE <C-v>
In console mode. Paste from clipboard.
.TP
.B KEY_CL_ERASE_CHAR <BS>
In console mode. Clear letter from command.

.SH MOUSE COMMANDS
Mouse buttons also can be changed in \fIconfig.h\fP file (BTN_* variables).
.TP
.B BTN_MAIN <LeftMouse>
Use current tool.
.TP
.B BTN_SEL_CIRC <RightMouse>
Display the selection circle. Hover over items and release the button to make a selection.
.TP
.B BTN_SEL_CIRC_ALTERNATIVE <A-RightMouse>
Display an alternative selection circle (e.g. different color options).
.TP
.B BTN_CANVAS_RESIZE <C-RightMouse>
Resize the canvas via dragging.
.TP
.B BTN_SCROLL_DRAG <MiddleMouse>
Drag to move the canvas.
.TP
.B BTN_SCROLL_UP / DOWN / LEFT / RIGHT (<Up>, <Down>, <S-Up>, <S-Down>)
Scroll the canvas in the respective direction.
.TP
.B BTN_ZOOM_IN / BTN_ZOOM_OUT <C-Up>/<C-Down>
Zoom in or out using the mouse.
.TP
.B BTN_COPY_SELECTION <S-LeftMouse>
Make selection with selection tool and drag it with this button to copy area (instead of move).
.TP
.B BTN_TRANS_MOVE <LeftMouse>
Drag to move the canvas or a selection in transform mode.
.TP
.B BTN_TRANS_MOVE_LOCK <S-LeftMouse>
Move along one axis while in transform mode.
.TP
.B BTN_TRANS_SCALE <A-RightMouse>
Scale the canvas or a selection in transform mode.
.TP
.B BTN_TRANS_SCALE_UNIFORM <A-S-RightMouse>
Uniformly scale while keeping the aspect ratio intact.
.TP
.B BTN_TRANS_ROTATE <C-RightMouse>
Rotate the canvas or current selection by moving the mouse vertically.
.TP
.B BTN_TRANS_ROTATE_SNAP <C-S-RightMouse>
Rotate with predefined 45° snapping increments.

.SH NOTE
All listed keys are in vim notation.

.SH HOMEPAGE
https://github.com/Familex/xpaint