onon 0.8.1

This page is generated from the same registries used by the application.

Configuration options

Assign options with onon.options.<name> = <value> in Lua or :set <name>=<value> at runtime. Colors use { r, g, b } in Lua and r,g,b or #RRGGBB with :set.

Option	Type	Default	Description
alt_colors	boolean	false	Start with alternate colors: true, false, or “system” to follow the OS’s dark mode as it changes.
alt_colors_keep_images	boolean	true	Keep raster images in their own colors in alternate-color mode.
anchor_position	string	"center"	Viewport anchor: center, top, or bottom.
animation_frame_ms	integer	0	Animation timestep in milliseconds; 0 follows the display’s refresh rate.
annotation_colors	table	{"#ffe066", "#8ce99a", "#74c0fc", "#ffa8a8"}	Highlight colours offered by the highlight picker, as #RRGGBB.
anti_aliasing	integer	8	MuPDF antialiasing level from 0 through 8.
auto_reload	boolean	true	Reload the document when its file changes on disk.
auto_reload_delay_ms	integer	200	Milliseconds a changed file must stay unwritten before it reloads, so a file being written reloads once.
autoscroll_max_speed	number	20000	Fastest autoscroll speed in pixels per second, however far the pointer is from the anchor; 0 or less removes the limit.
autoscroll_speed_factor	number	1	Multiplier for autoscroll speed at every pointer distance from the anchor, up to autoscroll_max_speed; clamped to at least 0.01.
completion_max_items	integer	10	Maximum command-completion rows.
copy_on_select	boolean	true	Copy selected text to the clipboard when the mouse selection is released.
dual_page	boolean	false	Start in dual-page mode.
first_page_offset	boolean	true	Treat the first page as a standalone cover in dual-page mode.
fit_mode	string	"page"	Initial fit mode: page, width, height, or manual.
hint_chars	string	"asdfghjkl"	Characters used for link hint labels, in order of preference.
invert_scroll	boolean	false	Invert horizontal and vertical discrete mouse-wheel scrolling.
invert_smooth_scroll	boolean	false	Invert horizontal and vertical smooth wheel or trackpad scrolling.
link_preview	boolean	true	Preview the destination of an internal link after hovering it briefly.
link_preview_delay_ms	integer	400	Milliseconds to hover an internal link before its preview appears.
link_schemes	table	{"http", "https", "mailto"}	URI schemes that document links may open externally; other links only show their target.
loading_indicator	boolean	true	Animate a loading indicator on pages still rendering for the first time.
max_zoom	number	8	Maximum manual zoom scale.
min_zoom	number	0.5	Minimum manual zoom scale.
mouse_text_select	boolean	true	Enable text selection with the left mouse button.
mupdf_store_mb	integer	256	MuPDF cache for fonts and decoded images in MiB; applies to newly opened documents.
outline_height_percent	integer	80	Outline overlay height as a percentage of the window.
outline_initial_depth	integer	1	Outline levels expanded when the outline opens.
outline_width_percent	integer	70	Outline overlay width as a percentage of the window.
overview_gap	integer	16	Gap in pixels between the page overview’s cells.
overview_max_columns	integer	12	Most columns the page overview shows, whether fitted to the window or set with zoom_out.
overview_thumb_width	integer	220	Width in pixels the page overview aims to show each page at, which sets how many columns fit.
page_cache_memory_mb	integer	512	Maximum memory in MiB for cached page renders; 0 disables the limit.
page_cache_size	integer	0	Deprecated and ignored; the cache is bounded by page_cache_memory_mb.
page_gap	integer	0	Vertical gap between pages; aliases page_gap_vertical.
page_gap_horizontal	integer	0	Horizontal gap between pages in a spread.
page_gap_vertical	integer	0	Vertical gap between page rows.
pinch_sensitivity	number	1	Trackpad pinch zoom sensitivity; 1 preserves the gesture scale.
prompt_history_max	integer	100	Maximum entries kept in each of the command and search prompt histories; 0 keeps none.
recent_files_max	integer	20	Maximum recent files retained and displayed.
render_mode	string	"continuous"	Initial render mode: continuous or single.
render_oversample	number	1	Render scale multiplier; values above 1 supersample.
render_threads	integer	0	Page rendering threads; 0 picks one per core up to 4, leaving a core free. Applies to newly opened documents.
renderer	string	"auto"	Renderer SDL draws with, read when onon starts: “auto” for SDL’s own choice, “gpu” for its GPU renderer (Vulkan, Metal or Direct3D 12), or one of SDL’s drivers, such as “vulkan”, “opengl”, “metal”, “direct3d11” or “software”. One that cannot start falls back to “auto”; SDL_RENDER_DRIVER in the environment overrides it.
scroll_off	integer	1	Minimum number of rows kept visible above and below the selected item in UI menus, like Vim’s scrolloff.
scroll_step	integer	64	Keyboard and mouse scroll distance in pixels.
sequence_timeout_ms	integer	700	Maximum delay between keys in a binding sequence.
session_database	boolean	true	Persist per-document view state, marks, and recent files.
smooth_scroll	table	{ mouse = true, trackpad = true, keyboard = true }	Animate scrolling for selected inputs; assignments update only specified mouse, trackpad, and keyboard fields.
smooth_scroll_dampening	number	0.8	Catch-up factor for smooth scrolling per animation frame; higher values are more responsive and less damped; clamped to 0.01 through 1.
smooth_zoom	table	{ mouse = true, trackpad = true, keyboard = true }	Animate zooming for selected inputs; assignments update only specified mouse, trackpad, and keyboard fields.
smooth_zoom_dampening	number	0.8	Catch-up factor for smooth zooming per animation frame; higher values are more responsive and less damped; clamped to 0.01 through 1.
spread_gap	integer	0	Horizontal spread gap; aliases page_gap_horizontal.
status_bar_left	string	"{modified}{message}"	Left status bar template.
status_bar_right	string	"{document} {label}/{total} {zoom}"	Right status bar template.
status_bar_visible	boolean	true	Show the status bar.
trim_margins	boolean	false	Lay pages out by their content, trimming blank margins.
trim_padding	integer	8	Margin in points kept around a page’s content when trimming margins.
zoom_step	number	1.15	Factor zoom_in multiplies the zoom by, and zoom_out divides it by; above 1.

Theme

The theme is everything about how the viewer looks: its colours, UI font and the shape of its panels. Assign it as one table, so a theme can be shared as a single table:

onon.theme = {
  base = "birch",  -- start from a built-in theme; the default is moss
  accent = "#335533",
  alt = { accent = "#88aa88" },
  font = { family = "Iosevka", size = 14 },
}

require searches the configuration file’s directory first, so a theme can live in a file of its own beside config.lua. Have it return its table, as themes/forest.lua holding return { accent = "#2f5d3a" }, and apply it with onon.theme = require("themes.forest"); dots in the name are directories, and require("forest") would load forest.lua.

:theme lists the built-in themes and the theme files, each named for its file: those in themes/ beside config.lua, then those in each directory plugins are searched for with themes in place of plugins, as /usr/lib/onon/themes and ~/.config/onon/themes on Linux. Where two directories have a file of the same name, the first wins. :theme shows each one as it is selected: Enter keeps it, Esc puts back the theme before, and :theme <name> switches straight to one. A file named for a built-in theme is left out. The theme chosen is remembered and applied before config.lua runs, so what config.lua changes field by field, as onon.theme.accent = "#335533" does, changes the chosen theme too; assigning onon.theme whole replaces it, and :theme then says that a theme it picks lasts only until onon restarts.

Fields left out keep the base theme’s values. Assign a preset by name with onon.theme = "birch", or a single field with onon.theme.accent = "#335533"; at runtime use :set theme=birch or :set theme.accent=#335533. Built-in themes: birch, classic, and moss. onon.themes.<name> gives a copy of one to change. Fields and element properties this version does not know are skipped with a warning, so a theme written for a newer version still loads; :set refuses them.

Colours are "#RRGGBB" or { r, g, b }. The alt table holds the colours used in alternate-color mode, toggled with :colors, and has the same colour fields as the theme. The font table picks the UI font; with neither family nor path set it is the system’s interface font.

The motion table sets how the UI moves. Each transition is written as CSS writes one, a duration and an easing such as "140ms ease-out", or as { duration = 140, easing = "ease-out" }; easings are linear, ease, ease-in, ease-out, ease-in-out and cubic-bezier(x1, y1, x2, y2), and "none" turns one transition off. By default only what moves is animated: the selection, the cursor and the sides of the status bar glide to where they go, while menus and messages appear and go at once; give panel or message a transition to fade them. scale slows or speeds every transition, and 0 turns motion off altogether, as the classic theme does.

Field	Type	Default	Description
background	color	"#e6e4dd"	Canvas behind the pages.
page	color	"#ffffff"	Paper of pages still rendering.
foreground	color	"#2a2e29"	UI text.
muted	color	"#737a70"	Secondary UI text, such as menu details and the right of the status bar.
accent	color	"#4d7044"	Prompts, link hints, headings, the selected menu row’s ribbon and the overview’s selected page.
panel	color	"#fbfaf7"	Background of menus, completion and other panels.
border	color	"#d5d2c9"	Hairlines around panels and above the status bar.
status_bar	color	"#f1f0eb"	Status bar background.
selection	color	"#bfd9a9"	Highlight of selected text.
search	color	"#f2dc8c"	Highlight of search matches.
search_current	color	"#eaa660"	Highlight of the current search match.
hint_foreground	color	"#fbfaf7"	Text of link hints, set on the accent.
presentation	color	"#0f110f"	Background around the page in presentation mode.
alt.background	color	"#121412"	Canvas behind the pages in alternate-color mode.
alt.page	color	"#1f2420"	Paper of pages still rendering, and of pages recoloured in alternate-color mode.
alt.foreground	color	"#d9dfd4"	UI text, and the ink of pages recoloured in alternate-color mode.
alt.muted	color	"#8b9487"	Secondary UI text, such as menu details and the right of the status bar in alternate-color mode.
alt.accent	color	"#9dc48b"	Prompts, link hints, headings, the selected menu row’s ribbon and the overview’s selected page in alternate-color mode.
alt.panel	color	"#232823"	Background of menus, completion and other panels in alternate-color mode.
alt.border	color	"#363c35"	Hairlines around panels and above the status bar in alternate-color mode.
alt.status_bar	color	"#1c1f1c"	Status bar background in alternate-color mode.
alt.selection	color	"#4f6b45"	Highlight of selected text in alternate-color mode.
alt.search	color	"#7a6a32"	Highlight of search matches in alternate-color mode.
alt.search_current	color	"#9a6430"	Highlight of the current search match in alternate-color mode.
alt.hint_foreground	color	"#1c1f1c"	Text of link hints, set on the accent in alternate-color mode.
alt.presentation	color	"#0f110f"	Background around the page in presentation mode in alternate-color mode.
font.family	string	""	Installed UI font family; empty uses the system interface font, such as SF on macOS or Segoe UI on Windows.
font.path	string	""	UI font file; overrides font.family, font.style and font.weight.
font.size	integer	13	UI font size in logical pixels, scaled up on high-density displays.
font.weight	font-weight	400	UI font weight as CSS number 100-900 or alias such as normal, medium, semibold, bold, or black.
font.style	string	"normal"	UI font style: normal, italic, or oblique.
radius	integer	3	Corner radius of panels, menu rows and the status pill in logical pixels; 0 gives square corners.
padding	integer	8	Space around UI text in menu rows, panels and the status bar, in logical pixels.
shadow	boolean	true	Draw a soft shadow under floating panels.
status_bar_style	string	"bar"	Status bar layout: bar along the bottom of the window, or pill, floating over the page.
status_bar_padding	integer	10	Horizontal status bar padding in logical pixels.
motion.scale	number	1	Speed of every transition: 1 as given, 2 twice as slow, 0 for no motion at all, as when the OS is set to reduce motion.
motion.panel	transition	"none"	Menus and completion fading in as they open, and menus fading out as they close.
motion.selection	transition	"80ms ease-out"	The selected row’s highlight gliding to the next row selected.
motion.prompt	transition	"100ms ease-out"	The sides of the status bar growing and shrinking with their text, as a pill does when a prompt opens.
motion.message	transition	"none"	Status messages fading in, and out when cleared.
motion.cursor	transition	"50ms ease-out"	The prompt’s cursor gliding to where it moves.

Elements

Each piece of the UI is an element with a style of its own, which the theme’s elements table changes. The fields above still shape every element: an element’s style starts from the theme’s radius, padding, shadow and status_bar_style, and from the element it inherits from, and the properties set here go over that.

onon.theme = {
  elements = {
    panel = { radius = 12, shadow = "0 8 24 shadow" },
    row_selected = { fill = "accent", text = "panel" },
    status_left = { shape = "pill" },
  },
}

Set one property with onon.theme.elements.panel.radius = 12, or at runtime with :set theme.elements.panel.radius=12. Reading a property gives the value in effect, and assigning nil returns it to its default. The status_bar_style field picks the defaults of status, status_left and status_right: bar lays a bar along the bottom of the window, and pill floats a pill for each side over the page.

Colours name a palette colour, which follows the color mode, or are "#RRGGBB", "#RRGGBBAA" or "none"; any can be followed by an opacity percentage, as "accent/16". The name shadow is black at the strength shadows need over the background. Lengths are logical pixels, scaled on high-density displays.

Property	Type	Description
shape	shape	“rect”, with corners rounded by radius; “pill”, with round ends; SVG-like path data; or a function(path, w, h) drawing the path. See Shapes.
radius	corners	Corner radius of a rect in logical pixels: one number, or { top_left, top_right, bottom_right, bottom_left }.
fill	color	Colour of the box; “none” for no box.
border.width	number	Width of the border inside the box’s edge in logical pixels; 0 for none.
border.color	color	Colour of the border.
border.sides	sides	Sides the border is drawn on: “all”, or some of “top”, “right”, “bottom” and “left”.
shadow	shadow	Shadows under the box: false; true for the default; { x, y, blur, spread, color }, or a list of them; or CSS box-shadow text such as “0 3 8 shadow, 0 1 2 shadow/50”.
opacity	number	Opacity of the whole element, from 0 to 1.
text	color	Colour of the text.
secondary	color	Colour of secondary text, such as a row’s detail.
bold	boolean	Draw the text in the heavier heading weight.
padding	insets	Space between the box’s edges and its contents in logical pixels: one number, { vertical, horizontal }, or { top, right, bottom, left }.
margin	insets	Space around the box in logical pixels, written as padding is.
width	number	Width in logical pixels.
gap	number	Space between the element’s parts in logical pixels.
floating	boolean	Float over the page rather than take space from it.
draw	function	A function(canvas, box, state) that draws the box in place of the default drawing. See Drawing.

Every element starts from shape = "rect", radius = 0, fill = "none", border = { width = 0, color = "border", sides = "all" }, shadow = "none", opacity = 1, text = "foreground", secondary = "muted", bold = false, padding = 0, margin = 0, width = 1, gap = 0, floating = false, draw = nil. The elements, with what their styles change from that in the default theme:

Element	Description	Properties	Default style
panel	Menus and other floating panels. Its padding surrounds a menu’s header and rows.	shape, radius, fill, border, shadow, opacity, draw, padding	radius = 3, fill = "panel", border = { width = 1 }, shadow = "0 2 1 0 shadow", padding = { 0, 0, 8, 0 }
completion	The completion panel above the prompt. Its padding surrounds its rows. Starts from panel.	shape, radius, fill, border, shadow, opacity, draw, padding	radius = 3, fill = "panel", border = { width = 1 }, shadow = "0 2 1 0 shadow", padding = { 4, 0 }
header	A menu’s title, a line of text with its padding around it. Its secondary colour is for the count or query after the title, set off by gap.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding, gap	radius = { 3, 3, 0, 0 }, border = { width = 1, sides = "bottom" }, bold = true, padding = { 4, 14 }, gap = 8
row	A row of a menu or of completion. Its secondary colour is for key bindings and the detail on the right. Its padding above and below sets the height of rows.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	padding = { 4, 14 }
row_selected	The selected row. Starts from row.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	fill = "accent/10", border = { width = 3, color = "accent", sides = "left" }, padding = { 4, 14 }
row_disabled	A row that cannot be chosen. Starts from row.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	text = "muted", padding = { 4, 14 }
heading	A section title among a menu’s rows. Starts from row.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	text = "accent", bold = true, padding = { 4, 14 }
button	A button in a menu, such as the keybind menu’s new keybind. Starts from row.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	radius = 3, border = { width = 1 }, text = "accent", padding = { 4, 14 }
scrollbar	The thumb of a menu’s scrollbar; margin.right sets it off the panel’s edge.	shape, radius, fill, border, shadow, opacity, draw, width, margin	shape = "pill", fill = "muted/56", margin = { 0, 5, 0, 0 }, width = 4
swatch	A colour sample before a row’s text, gap before the text.	shape, radius, fill, border, shadow, opacity, draw, gap	radius = 1.5, border = { width = 1 }, gap = 8
status	The status bar as a whole: margin sets it off the window’s edges, gap between its sides, and floating draws it over the page instead of below it.	shape, radius, fill, border, shadow, opacity, draw, margin, gap, floating	fill = "status_bar", border = { width = 1, sides = "top" }
status_left	The left of the status bar, holding messages and prompts. Its padding above and below sets the bar’s height.	shape, radius, fill, border, shadow, opacity, draw, text, padding	padding = { 4, 10 }
status_right	The right of the status bar; the sides of its padding set its text in. Starts from status_left.	shape, radius, fill, border, shadow, opacity, draw, text, padding	text = "muted", padding = { 4, 10 }
prompt	A prompt’s prefix, such as : or /.	text	text = "accent"
cursor	The text cursor in a prompt.	shape, radius, fill, border, shadow, opacity, draw, width	fill = "accent"
input_selection	Selected text in a prompt.	shape, radius, fill, border, shadow, opacity, draw	fill = "accent/30"
hint	A link hint label. Its secondary colour is for the letters already typed.	shape, radius, fill, border, shadow, opacity, draw, text, secondary, bold, padding	radius = 1.5, fill = "accent", text = "hint_foreground", secondary = "hint_foreground/55", bold = true, padding = { 2, 5 }
overview_selection	The outline around the overview’s selected page; padding is its distance from the page.	shape, radius, fill, border, shadow, opacity, draw, padding	radius = 3, border = { width = 2.5, color = "accent" }, padding = 3
link_preview	The popup previewing a link’s target, a rect with corners rounded by its radius. Its fill shows while the page renders.	radius, fill, border, shadow, opacity, draw	radius = 3, fill = "page", border = { width = 1 }, shadow = "0 2 1 0 shadow"
title_bar	Behind the window buttons onon draws where the system draws no title bar, as on Windows. Its text colour draws the buttons’ symbols.	shape, radius, fill, border, shadow, opacity, draw, text	fill = "status_bar"
title_button	A window button under the pointer, drawn a little fainter while pressed.	shape, radius, fill, border, shadow, opacity, draw, text	fill = "foreground/15"
title_close	The close button under the pointer. Starts from title_button.	shape, radius, fill, border, shadow, opacity, draw, text	fill = "#c42b1c", text = "#ffffff"
loader	The drops bouncing on a page still rendering; its box is the page.	fill, opacity, draw	fill = "muted"
autoscroll_marker	The marker where autoscroll started: its fill, its outline as its border, and its width.	fill, border, opacity, width, draw	fill = "#fafafad7", border = { width = 1.2, color = "#282828e6" }, width = 32
page	Each page of the document, its fill showing until the page renders. Pages turned other than by quarter turns are drawn plain.	shape, radius, fill, border, shadow	fill = "page", shadow = "0 2 1 0 shadow"

Shapes

A rect has its corners rounded by radius, and a pill has round ends whatever its size. Any other shape is a path, given as SVG path data or drawn by a Lua function. The border is drawn inside the shape’s edge, and shadows follow the shape.

Path data takes the commands M, L, H, V, Q, C and Z, lowercase for relative coordinates. A coordinate is in logical pixels from the box’s top left, or a percentage of the box’s width or height, offset by pixels written straight after it. This arrow points right whatever the row’s width:

onon.theme.elements.row_selected.shape = "M0,0 H100%-8 L100%,50% L100%-8,100% H0 Z"

A function is called as shape(path, w, h) with the box’s size in logical pixels, whenever an element is drawn at a size not drawn before. Its path has the methods move_to(x, y), line_to(x, y), quad_to(cx, cy, x, y), cubic_to(c1x, c1y, c2x, c2y, x, y), close(), rect(x, y, w, h [, radius]) and ellipse(cx, cy, rx [, ry]), each returning path. If a shape fails, its element is drawn as a plain rect and the error is reported once.

onon.theme.elements.status_left.shape = function(path, w, h)
  path:move_to(h / 2, 0):line_to(w, 0):line_to(w - h / 2, h):line_to(0, h):close()
end

Drawing

An element’s draw function draws its box in place of the default drawing, as draw(canvas, box, state), each time the element is drawn; its text is drawn over it as usual. box holds the box’s x, y, w and h in logical pixels from the window’s top left, and state the element being drawn, whether alt colours are on, and the time in seconds since onon started, for drawing that moves, so a function set on row can tell row_selected apart. Both tables are reused from call to call, so copy what you keep. Like other properties, a draw function carries to the elements that start from its element; assigning false or nil removes it.

The canvas’s coordinates are logical pixels from the box’s top left, and may reach outside it. Its methods are:

Method	Draws
canvas:default()	The element as it would be drawn without the function: its box, or the loader’s drops and the autoscroll marker.
canvas:fill(path, color)	The inside of a path: path data as a shape takes, or a path from canvas:path().
canvas:stroke(path, color [, width])	A line along a path, 1 logical pixel wide unless given, with round joins.
canvas:rect(x, y, w, h, color [, radius])	A rect, its corners rounded by radius.
canvas:text(x, y, text, color [, bold])	Text with the top of its line at y, in the UI font; returns its width.
canvas:measure(text [, bold])	Nothing; returns the width and line height of text.
canvas:path()	Nothing; returns an empty path, with the methods a shape function’s path has.

Colours are written as in the elements table, and the element’s opacity applies to them. Panels and the link preview draw their border over their contents, which they do only when the function called canvas:default(). If the function fails, the element is drawn as it would be without it, the error is reported once, and the function is not called again until the configuration changes.

onon.theme.elements.row_selected.draw = function(canvas, box, state)
  canvas:default()
  canvas:rect(0, 5, 3, box.h - 10, "accent", 1.5) -- a bar at the left
end

Commands

Command	Description
:back	Jump back to the previous position
:colors normal|alt	Set color mode
:config	Open the config file in a text editor, creating it if there is none
:copy	Copy the selection
:cover [on|off]	Show the first page alone in dual-page mode
:dual [on|off]	Toggle or set dual-page mode
:fit width|height|page|manual	Set fit mode
:forward	Jump forward again after :back
:fullscreen [on|off]	Toggle or set fullscreen
:help	Show commands, key bindings, search flags and options
:highlight	Highlight the selection in the last colour used
:hints	Label links on screen to follow one by typing its hint
:keybinds	Toggle the keybinds menu
:lua <code>	Execute Lua code inline
:matches	List every match of the current search
:mode continuous|single	Set render mode
:next	Go to the next search match
:noh	Clear the search highlights
:open <filename>	Open another PDF relative to the current document
:open_file_picker	Open the PDF file picker
:outline	Open the document outline
:overview	Toggle the page overview grid
:page PAGE, :p PAGE, :N	Jump to a page number or label
:present	Toggle presentation mode
:prev	Go to the previous search match
:print [lp options]	Print the saved document from a dialog, or directly with lp options such as -d office -P 1-3
:quit, :q	Exit; :q! discards unsaved edits
:recent	Open the recent-files menu
:redo	Reapply the last undone edit
:reload-config	Reload the config file
:rotate [cw|ccw|DEGREES]	Rotate by a quarter turn, or to 0, 90, 180 or 270
:search [-r] [-i] [-w] [-p] <text>	Search document text
:set [option[?]|option!|option=value]	Inspect or change options
:statusbar [on|off]	Show or hide the status bar
:theme [name]	Pick a theme, seeing each as it is selected, or switch to one
:trim [on|off]	Lay pages out by their content, trimming margins
:undo	Undo the last edit
:version	Show the onon version
:write [path], :w	Save edits, or a copy to path; :wq saves and exits
:zoom in|out|reset|PERCENT	Zoom a step, reset, or set e.g. :zoom 150

Search flags: -r regular expression, -i ignore case, -w whole word, -p current page only. Flags can be combined.

Lua functions

The index below is followed by a detailed entry for every function. Lua errors are raised as protected-call errors; use pcall when a script should handle them without aborting the current dispatch.

Index

Function	Summary
onon.bind(key, action)	binds a key sequence to an action or Lua callback.
onon.bind_mouse(event, action)	binds a mouse event to an action or Lua callback.
onon.cache.clear()	drops all rendered tiles and thumbnails.
onon.cache.entries()	returns the number of cached page tiles and thumbnails.
onon.cache.limit([mib])	reads or changes the render cache memory limit in MiB.
onon.cache.pending()	returns the number of queued tile renders.
onon.clear_pending_keys()	clears pending key, mark, and numeric-count input.
onon.clipboard.get_text()	returns the current clipboard contents as UTF-8 text.
onon.clipboard.set_text(text)	replaces the clipboard with UTF-8 text.
onon.command(command)	executes a viewer command.
onon.current_count()	returns the pending numeric action count.
onon.fit_mode([mode])	reads or changes the fit mode. Valid modes are manual, page, width, and height.
onon.formats.extensions()	returns extensions supported by the linked document engine.
onon.formats.supports(path)	checks whether a path extension names a supported format.
onon.fullscreen([enabled])	reads or changes fullscreen state.
onon.goto_document_point(spec)	moves to a page coordinate in document space.
onon.log(level, message)	writes a diagnostic without changing the user-facing message.
onon.message([text])	reads or replaces the viewer’s status message.
onon.mode()	returns the current viewer input mode.
onon.open(path)	opens another document.
onon.open_external(uri_or_path)	asks the operating system to open a URI or path.
onon.page([page])	reads or changes the current physical page.
onon.page_count()	returns the current document’s page count.
onon.pending_keys()	returns pending key-sequence tokens.
onon.pick_directory(callback)	opens the native directory picker and invokes a callback with its result.
onon.pick_file(callback)	opens the native document picker, filtered to the formats this build can open, and invokes a callback with its result.
onon.plugin.register(id[, spec])	registers and returns a lazily loaded plugin module.
onon.recent_files([limit])	returns recent document paths.
onon.render_mode([mode])	reads or changes the render mode. Valid modes are continuous and single.
onon.rotation([degrees])	reads or changes clockwise rotation in degrees.
onon.schedule(callback)	queues a callback on the main Lua thread after the current dispatch.
onon.search(query[, backward])	starts an asynchronous document search.
onon.search_match_count()	returns the number of discovered search matches.
onon.search_match_index()	returns the current search match index.
onon.search_query()	returns the active search query.
onon.ui.create(spec)	creates a searchable list view.
onon.unbind(key)	removes a key binding.
onon.unbind_mouse(event)	removes a mouse binding.
onon.version()	returns onon’s version.
onon.zoom([scale])	reads or changes the zoom and clamps values to the configured range.

onon.bind(key, action)

binds a key sequence to an action or Lua callback.

Parameters

• key: A printable key, special key name, modified key, or multi-key sequence, such as j, <PgDn>, <C-p>, or gg. See Key and mouse names.
• action: A bindable action such as onon.next_page, or a Lua callback.

Returns

Nothing. A later binding replaces an earlier binding for the same key.

Errors

Raises an error when the key or action is invalid.

Example

onon.bind("<C-p>", function()
  onon.page(1)
end)

onon.bind_mouse(event, action)

binds a mouse event to an action or Lua callback.

Parameters

• event: A mouse event such as wheel_down, left_down, or <C-wheel_up>. See Key and mouse names.
• action: A bindable action or a Lua callback.

Returns

Nothing.

Errors

Raises an error when the event or action is invalid.

Example

onon.bind_mouse("<C-wheel_up>", onon.zoom_in)

onon.cache.clear()

drops all rendered tiles and thumbnails.

Returns

Nothing.

Example

onon.cache.clear()

onon.cache.entries()

returns the number of cached page tiles and thumbnails.

Returns

The number of rendered textures currently held in the render cache.

Example

onon.log("debug", tostring(onon.cache.entries()))

onon.cache.limit([mib])

reads or changes the render cache memory limit in MiB.

An omitted limit reads the current limit; supplying an integer changes it and returns the resulting limit. 0 removes the limit.

onon.cache.pending()

returns the number of queued tile renders.

Returns

The number of tile renders waiting to be processed.

Example

if onon.cache.pending() > 0 then onon.message("rendering") end

onon.clear_pending_keys()

clears pending key, mark, and numeric-count input.

Returns

Nothing.

Example

onon.clear_pending_keys()

onon.clipboard.get_text()

returns the current clipboard contents as UTF-8 text.

Returns

The current clipboard contents as UTF-8 text.

Errors

Raises an error when clipboard access is unavailable.

onon.clipboard.set_text(text)

replaces the clipboard with UTF-8 text.

Parameters

• text: UTF-8 text to place on the clipboard.

Returns

Nothing.

onon.command(command)

executes a viewer command.

Parameters

• command: A viewer command, with or without the leading colon.

Returns

Nothing.

Errors

Raises an error when the command is invalid or cannot be executed.

Example

onon.command(":fit width")

onon.current_count()

returns the pending numeric action count.

Returns

The pending numeric prefix as a string, or an empty string when no count is pending.

Example

onon.message("count: " .. onon.current_count())

onon.fit_mode([mode])

reads or changes the fit mode. Valid modes are manual, page, width, and height.

Parameters

• mode: Optional manual, page, width, or height value. Omit it to read the current mode.

Returns

The active fit mode.

Errors

Raises an error for an invalid mode or when setting it without a viewer host.

Example

onon.fit_mode("width")

onon.formats.extensions()

returns extensions supported by the linked document engine.

Returns

An alphabetically sorted array of lower-case extensions without leading dots.

Example

for _, extension in ipairs(onon.formats.extensions()) do
  onon.log("debug", extension)
end

onon.formats.supports(path)

checks whether a path extension names a supported format.

Parameters

• path: A path whose extension should be checked.

Returns

True when the extension names a format supported by the linked engine.

Behavior

This is an extension hint. Opening also sniffs content, so a missing or misleading extension may still open.

Example

if onon.formats.supports("book.epub") then onon.open("book.epub") end

onon.fullscreen([enabled])

reads or changes fullscreen state.

Parameters

• enabled: Optional boolean. Omit it to read the current state.

Returns

The current fullscreen state.

Example

onon.fullscreen(true)

onon.goto_document_point(spec)

moves to a page coordinate in document space.

Parameters

• spec: A table containing 1-based integer page and numeric x and y coordinates.

Returns

Nothing. Coordinates are measured from the page’s top-left corner in document points.

Example

onon.goto_document_point({ page = 3, x = 72, y = 144 })

onon.log(level, message)

writes a diagnostic without changing the user-facing message.

Parameters

• level: debug, info, warn, or error.
• message: Diagnostic text written to the application log, tagged with the plugin responsible, or config outside plugin code.

Returns

Nothing. The viewer’s user-facing message is unchanged.

Example

onon.log("info", "plugin loaded")

onon.message([text])

reads or replaces the viewer’s status message.

Parameters

• text: Optional replacement status message.

Returns

The current message as a string.

Example

onon.message("ready")
local current = onon.message()

onon.mode()

returns the current viewer input mode.

Returns

The current input mode: normal, command, goto, or search; nil without a viewer host.

Example

if onon.mode() == "normal" then onon.message("ready") end

onon.open(path)

opens another document.

Parameters

• path: A document path. Relative paths resolve from the current document directory.

Returns

Nothing. Opening is applied by the viewer after the current Lua dispatch.

Errors

Raises an error when the document cannot be opened.

Example

onon.open("appendix.pdf")

onon.open_external(uri_or_path)

asks the operating system to open a URI or path.

Parameters

• uri_or_path: A URI or filesystem path for the operating system’s default application.

Returns

Nothing.

Errors

Raises an error when the operating-system opener cannot be started.

Example

onon.open_external("https://example.com")

onon.page([page])

reads or changes the current physical page.

Parameters

• page: Optional 1-based physical page number to navigate to.

Returns

The current 1-based page number, or nil when no document is open.

Example

local page = onon.page()
onon.page(page + 1)

onon.page_count()

returns the current document’s page count.

Returns

The number of pages, or nil when no document is open.

Example

if (onon.page_count() or 0) > 100 then onon.message("long document") end

onon.pending_keys()

returns pending key-sequence tokens.

Returns

An array of pending key-sequence tokens.

Example

for _, key in ipairs(onon.pending_keys()) do onon.log("debug", key) end

onon.pick_directory(callback)

opens the native directory picker and invokes a callback with its result.

Parameters

• callback: Receives { success, path, cancelled, error } after the native picker closes.

Returns

Nothing. The callback completes before this function returns.

Example

onon.pick_directory(function(result)
  if result.success then onon.message(result.path) end
end)

onon.pick_file(callback)

opens the native document picker, filtered to the formats this build can open, and invokes a callback with its result.

Parameters

• callback: Receives { success, path, cancelled, error } after the native picker closes.

Returns

Nothing. The picker and callback complete before this function returns.

Errors

Raises an error when the callback fails.

Example

onon.pick_file(function(result)
  if result.success then onon.open(result.path) end
end)

onon.plugin.register(id[, spec])

registers and returns a lazily loaded plugin module.

Parameters

• id: The plugin ID currently being loaded by require.
• spec: Optional plugin option declarations.

Returns

The plugin module table.

Errors

Raises an error when the ID is invalid, undiscovered, disabled, or does not match the plugin currently being loaded.

Example

local plugin = onon.plugin.register("my-plugin")

onon.recent_files([limit])

returns recent document paths.

Parameters

• limit: Optional maximum number of paths. Defaults to recent_files_max.

Returns

An array of document paths, or an empty array when session storage is disabled.

onon.render_mode([mode])

reads or changes the render mode. Valid modes are continuous and single.

Parameters

• mode: Optional continuous or single value. Omit it to read the current mode.

Returns

The active render mode.

Errors

Raises an error for an invalid mode or when setting it without a viewer host.

Example

onon.render_mode("single")

onon.rotation([degrees])

reads or changes clockwise rotation in degrees.

Parameters

• degrees: Optional clockwise rotation. Omit it to read the current rotation.

Returns

The normalized clockwise rotation, or nil without a viewer host.

Example

onon.rotation(90)

onon.schedule(callback)

queues a callback on the main Lua thread after the current dispatch.

Parameters

• callback: A zero-argument callback to run on the main Lua thread after the current dispatch.

Returns

An operation handle with numeric id, cancel(), and active() members.

Example

local handle = onon.schedule(function() onon.message("later") end)

onon.search(query[, backward])

starts an asynchronous document search.

Parameters

• query: Search text, optionally prefixed with -r, -i, -w, or -p flags.
• backward: Optional boolean selecting backward search.

Returns

Nothing. Matching runs asynchronously.

Example

onon.search("-iw introduction")

onon.search_match_count()

returns the number of discovered search matches.

Returns

The number of matches discovered so far. Search may still be running.

Example

onon.message(onon.search_match_count() .. " matches")

onon.search_match_index()

returns the current search match index.

Returns

The current 1-based match index, or nil when no match is focused.

Example

local index = onon.search_match_index()

onon.search_query()

returns the active search query.

Returns

The active query without search flags, or an empty string when search is inactive.

Example

local query = onon.search_query()

onon.ui.create(spec)

creates a searchable list view.

The spec may contain id, title, rows, selected, scroll, query, searchable, on_select, and on_close. Rows may be strings or row tables with text, value, id, secondary, depth, and disabled fields.

Returns

A view object with show, close, visible, row/query setters, and state accessors.

Example

local view = onon.ui.create({
  title = "Recent files",
  rows = onon.recent_files(10),
  on_select = function(_, path) onon.open(path) end,
})
view:show()

onon.unbind(key)

removes a key binding.

Parameters

• key: The key or key sequence to remove.

Returns

Nothing. Removing an unbound key is harmless.

Errors

Raises an error when the key is invalid.

Example

onon.unbind("<C-p>")

onon.unbind_mouse(event)

removes a mouse binding.

Parameters

• event: The mouse event to remove.

Returns

Nothing. Removing an unbound event is harmless.

Errors

Raises an error when the event is invalid.

Example

onon.unbind_mouse("middle_down")

onon.version()

returns onon’s version.

Returns

The release tag onon was built from, such as v0.7.0, or dev for a build not made from a tag.

Example

onon.log("info", "running onon " .. onon.version())

onon.zoom([scale])

reads or changes the zoom and clamps values to the configured range.

Parameters

• scale: Optional manual zoom scale. Omit it to read the current scale.

Returns

The current zoom scale, or nil without a viewer host.

Errors

Raises an error when the scale is invalid or cannot be set.

Example

onon.zoom(1.5)

UI views

Create views with local view = onon.ui.create(spec), then call view:show(). The specification supports id, title, rows, selected, scroll, query, searchable, on_select, and on_close. A row may be a string or a table with text, value, id, secondary, depth, and disabled.

View methods are show(), close(), visible(), set_rows(rows), set_selected(index), set_scroll(scroll), set_query(query), selected(), scroll(), and query(). Selection indices are 1-based, with 0 meaning no selection. on_select receives (index, value, text, id), preserving the original row index and ID when the list is filtered. on_close runs for user, programmatic, replacement, and document-close paths.

Portable API

The onon tables below are available to configuration and plugin Lua code.

Module	Returns / fields	Description
onon.platform	table	Also available from require("onon.platform"). Fields: os (linux, macos, or windows), arch, home_dir, config_dir, data_dir, cache_dir, and temp_dir. Directory fields are absolute when the platform supplies a location and may be empty when it does not.
onon.path	table	Also available from require("onon.path"). Fields: separator, list_separator; functions: join(...), clean(path), basename(path), dirname(path), extension(path), is_absolute(path), absolute(path), relative(base, target), and expand_home(path). Operations use native platform path rules; expand_home expands only ~, ~/..., and ~\....
onon.json	table	Also available from require("onon.json"). encode(value) returns compact JSON and decode(text) returns a Lua value. null is the stable module-local JSON null sentinel. Arrays require contiguous positive integer keys; objects require string keys. Cycles, sparse or mixed tables, non-finite numbers, unsupported Lua values, and trailing input are errors. Decoded empty arrays and objects retain their shape when re-encoded.

Document inspection

These read the open document. The onon.document fields path, name, extension, exists, size_bytes, and page_count remain available and are refreshed when the document changes. The functions below raise an error when no document is open. Rectangles are x0, y0, x1, y1 in unrotated PDF points.

Function	Returns / fields	Description
onon.document.metadata()	table	Return document metadata: format, encryption, title, author, subject, keywords, creator, producer, creation_date, and modification_date. Absent fields are empty strings.
onon.document.outline()	table[]	Return the outline as a tree. Each entry has title, uri, external, page, children, and optional x and y destination coordinates. page is 1-based, or 0 when the entry has no page destination.
onon.document.page_info(page)	table	Return page, label, width, height, and bounds for a 1-based page. Sizes are unrotated PDF points; an out-of-range page raises an error.
onon.document.selection()	table	Return the current selection: active, text, and pages, a list in page order of { page = n, quads = { ... } } with quads as bounding rectangles. pages is empty when nothing is selected.
plugin.document:page_text(page, callback)	handle	Extract a page’s text asynchronously. The result adds page and text.
plugin.document:page_links(page, callback)	handle	Read a page’s links asynchronously. The result adds page and links; each link has bounds, uri, external, page, and optional x and y.

Plugins

Plugins are discovered without being executed. Enable one explicitly with local plugin = require("plugin-id"); only the required plugin and its declared dependencies execute. The entrypoint must call onon.plugin.register("plugin-id"[, spec]); require returns the registered module.

A plugin manifest is onon-plugin.json with id, version, module, and dependencies; only id is required, and unrecognised fields are ignored. module selects lua/<module>.lua or lua/<module>/init.lua. Plugin modules contain id, version, actions, fs, timer, storage, http, and document, plus register_action, register_command, on, off, and job. Registered actions use plugin-id.action; commands use :plugin-id-command, where the command name cannot contain -; options use plugin-id.option.

Function	Returns / fields	Description
plugin.fs:read_dir(path[, options], callback)	handle	Read one directory asynchronously. options.follow_symlinks defaults to false. Without following, a symlink supplied as path is rejected; entries themselves are reported as symlinks.
plugin.fs:stat(path[, options], callback)	handle	Stat a path asynchronously. options.follow_symlinks defaults to false.
plugin.timer:after(ms, callback)	handle	Call callback() once after ms milliseconds. ms may be zero.
plugin.timer:every(ms, callback)	handle	Call callback() repeatedly, waiting ms milliseconds between dispatches. ms must be greater than zero.
plugin.storage:get(key)	value or nil	Synchronously return the value stored for this plugin ID, or nil when absent or when no session database is available.
plugin.storage:set(key, value)	none	Synchronously persist a plugin-scoped value. Supports nil, booleans, finite numbers, strings, contiguous arrays, and string-keyed objects; tables cannot be cyclic or mix array and object keys. Raises an error when no session database is available; the value is not silently discarded.
plugin.storage:delete(key)	none	Synchronously delete a plugin-scoped value.
plugin.storage:keys()	string[]	Synchronously return this plugin’s keys in lexical order.
plugin.http:request(spec, callback)	handle	Make an asynchronous HTTP request. spec has required url (http or https) and optional method (default GET), string-to-string headers, body, and positive timeout_ms.
plugin:job(spec, callback)	handle	Start a subprocess without invoking a shell. spec.command is required; optional fields are string-array args, cwd, positive timeout_ms, string-to-string env additions, and stdin.

Handles and results

Every schedule, filesystem, timer, HTTP, document-extraction, and job call returns a handle with numeric id, cancel(), and active(). active() becomes false before a one-shot completion callback runs. Repeating timers remain active between callbacks until cancelled. cancel() is idempotent, removes the operation, and does not invoke its callback, so delivered result tables always have cancelled=false. Callbacks run serially on the main Lua thread, never on worker goroutines.

Result	Returns / fields	Description
picker result	success, path, cancelled, error	Cancellation is a normal result: cancelled=true, success=false, empty path, and empty error.
fs.stat result	success, error, cancelled, timed_out; on success: name, path, type, size_bytes, modified_unix	type is file, directory, symlink, or other. modified_unix is whole seconds since the Unix epoch.
fs.read_dir result	success, error, cancelled, timed_out, entries	On success, entries is an array of the same file-information fields returned by stat.
http result	success, status, headers, body, error, timed_out, cancelled	On transport failure, status is 0 and body and headers are empty. Response header values are arrays of strings. HTTP error status codes are completed responses and do not by themselves set success=false.
job result	id, success, code, stdout, stderr, error, timed_out, cancelled	success requires exit code 0, no launch/wait error, and no timeout. code is -1 when no process exit code is available.

Limits

Resource	Returns / fields	Description
Storage value	65,536 bytes	Limit applies to the encoded JSON value for each key.
HTTP response body	8 MiB	A larger response fails the operation; request bodies have no API-specific size limit.
HTTP redirects	10	Following a redirect after the tenth redirect fails the operation.
Job stdout	4 MiB	Captured independently; additional output is discarded.
Job stderr	4 MiB	Captured independently; additional output is discarded.

Lifecycle

Each plugin has an isolated local-module cache and search root. It may require another discovered plugin by ID only when that ID is declared in dependencies. Dependencies load first, and events are delivered in activation order, so dependencies receive an event before their dependents. Registration of actions, commands, and event subscriptions is allowed only while the plugin entrypoint is loading; off(id), storage calls, timers, filesystem and HTTP operations, and jobs remain available afterward.

A successful :reload-config replaces the Lua state and cancels all handles and jobs from the old generation without invoking their callbacks. If reload fails, the previous state and its operations remain active. A failed plugin load rolls back that plugin and cancels work it started. Viewer shutdown emits shutdown before runtime close; close then cancels remaining operations and jobs. Storage is keyed by plugin ID in the session database and survives reloads and application restarts.

Supported events are app_ready, document_open_pre, document_opened, document_close_pre, document_closed, document_reloaded, config_reloaded, mouse_button_pre, mouse_button, selection_changed, page_changed, zoom_changed, option_changed, and shutdown. page_changed carries page, label, previous_page, and page_count; zoom_changed carries scale, previous_scale, and percent. Both are emitted once per frame with the settled value, so a continuous gesture reports where it came to rest. Event callbacks run in subscription order within each plugin; returning true marks an event consumed where the host supports consumption but does not stop later callbacks.

Plugins are found in every one of the platform plugin directories, and rescanned by :reload-config: on Linux /usr/lib/onon/plugins, $XDG_DATA_HOME/onon/plugins (or ~/.local/share/onon/plugins), $XDG_CONFIG_HOME/onon/plugins, ~/.config/onon/plugins and each $XDG_CONFIG_DIRS/onon/plugins; on macOS ~/Library/Application Support/onon/plugins and ~/.config/onon/plugins; on Windows %LOCALAPPDATA%\onon\plugins and %APPDATA%\onon\plugins. Where two have a plugin with the same id, the first wins. Disable plugin discovery with --no-plugins, or start from built-in defaults with --no-config, which also skips the generated settings file.

Single instance

Instances are per document. Each window listens on a socket named after the document it is showing, and the address follows the document when the window opens another one. --unique hands the request to the window already showing that document and exits; with no such window, this process opens it. --goto PAGE opens at a page and --goto PAGE:X:Y at a point on it, overriding any remembered session position, whether the work is done here or by an existing window. --command TEXT runs a viewer command there, as typed after :, including any command registered by a plugin. An unrecognised command exits non-zero. X and Y are points measured from the page’s top-left corner, which is also SyncTeX’s convention. Sockets live under $XDG_RUNTIME_DIR/onon on Linux, the per-user temporary directory on macOS, and %LOCALAPPDATA%\onon on Windows. They are mode 0600 and named by a hash of the document path, which keeps them within the platform socket length limit. A socket left by a crashed process is reclaimed on the next start.

Key and mouse names

onon.bind and onon.unbind take a key sequence; onon.bind_mouse and onon.unbind_mouse take a mouse event. An unknown name is an error. To find the name of a key, bind it in :keybinds, which records the keys you press.

Keys

A sequence is one or more keys written one after another, such as gg, g? or <C-w>j. Each key must follow the one before within sequence_timeout_ms. Digits 1 to 9 start a count, as in 5j or 12g, and ' and " jump to and set marks, so binding a sequence that begins with any of them is an error.

Printable keys are written as the character they type with the current keyboard layout, so on a US keyboard Shift+1 is !. Letters are case-sensitive: J is Shift+j, or j with Caps Lock on. On layouts without Latin letters, letter keys are read as their QWERTY letters. Write < as <lt>.

Other keys are written by name in angle brackets. Names are case-insensitive.

Name	Key
<CR>	Enter, Return or keypad Enter; also <Enter> and <Return>.
<Esc>	Escape; also <Escape>.
<Tab>	Tab.
<BS>	Backspace; also <Backspace>.
<Del>	Delete; also <Delete>.
<Ins>	Insert; also <Insert>.
<Space>	Space.
<Up>, <Down>, <Left>, <Right>	Arrow keys.
<PgUp>	Page Up; also <PageUp>.
<PgDn>	Page Down; also <PageDown>.
<Home>	Home.
<End>	End.
<F1> to <F24>	Function keys.
<k0> to <k9>	Keypad digits.
<kPlus>, <kMinus>, <kMultiply>, <kDivide>, <kPoint>	Keypad operators.

Modifiers

Modifiers go inside the brackets before the key name, as in <C-p>, <C-S-Tab>, <A-Left> or <D-c>.

Prefix	Modifier
C-	Ctrl.
A-	Alt; Option on macOS. M- is the same.
D-	Cmd on macOS; the Super or Windows key elsewhere.
S-	Shift.

Ctrl, Alt and Cmd combine with any key: letters, digits, symbols and the names above, as in <C-a>, <C-=>, <A-Space> or <D-Up>. With them, a key is named by its unshifted character and Shift is written out: <C-S-r> is Ctrl+Shift+r, <C-S-1> is Ctrl+Shift+1, <A-j> is Alt+j, whatever character Option+j types on macOS, and <C-R> is Ctrl+r. Write > as <gt> after a modifier, as in <C-gt>. Without Ctrl, Alt or Cmd, Shift applies to named keys, as in <S-Tab> or <S-F5>, and <S-j> means J; for other printable keys, write the shifted character. While a prompt is open, a character pressed with Alt alone is typed rather than running its binding, since Option on macOS and AltGr elsewhere type characters of their own.

Modifiers may be written in any order, so <C-S-Tab>, <s-c-tab> and <S-C-TAB> are the same key. Bindings are stored and shown in the first form, with modifiers in C, A, D, S order.

Editing a prompt

While a prompt is open, these keys edit its text before any binding of theirs runs. On every system, Left and Right move a character and with Ctrl a word, Home and End go to the ends, Shift with any of them selects, Backspace and Delete delete a character and with Ctrl a word, <C-w> deletes the word before the cursor, and <C-v> pastes. Up and Down step through the prompt’s history. <C-a> on Windows and Linux, and <D-a> on macOS, selects all of it.

On macOS, prompts also edit as Mac text fields do: Option with Left, Right, Backspace or Delete works by word, Cmd with Left or Right goes to the ends and Cmd-Backspace deletes to the start, and <C-a>, <C-e>, <C-b>, <C-f>, <C-h>, <C-d> and <C-k> work as in Emacs.

Mouse events

Event	Fires on
left_down, left_up	Pressing or releasing the left button.
middle_down, middle_up	The middle button.
right_down, right_up	The right button.
x1_down, x1_up, x2_down, x2_up	The side buttons, usually back and forward.
wheel_up, wheel_down	Each step of the vertical wheel.
wheel_left, wheel_right	Each step of the horizontal wheel or a sideways tilt.
<C-wheel_up>, <C-wheel_down>	The vertical wheel with Ctrl held.

Button events take no modifiers, and the horizontal wheel does nothing while Ctrl is held. Event names are case-insensitive and may be written in angle brackets like keys: <middle_down> is middle_down. - may be written for _, and ctrl_wheel_up is the same as <C-wheel_up>.

A bound button event replaces that button’s built-in behaviour, such as text selection and following links on the left button. Wheel directions scroll smoothly only while they are bound to their default scroll actions.

Bindable actions

Every action is available as onon.<action>, can be passed to onon.bind, and can be called from a runtime Lua callback.

Keys in a system’s own column are bound there as well as the default keys.

Action	Default keys	macOS	Windows	Linux	Countable
next_page	J, <PgDn>				true
prev_page	K, <PgUp>				true
scroll_down	j, <Down>				true
scroll_up	k, <Up>				true
scroll_left	h, <Left>				true
scroll_right	l, <Right>				true
next_spread					true
prev_spread					true
first_page	gg	<D-Up>	<C-Home>	<C-Home>	false
last_page	G	<D-Down>	<C-End>	<C-End>	false
command_mode	:				false
search_prompt	/	<D-f>	<C-f>	<C-f>	false
search_prompt_backward	?				false
search_next	n	<D-g>	<F3>	<F3>	true
search_prev	N	<D-S-g>	<S-F3>	<S-F3>	true
toggle_dual_page	d				false
toggle_render_mode	m				false
toggle_alt_colors	<C-r>				false
toggle_first_page_offset	co				false
toggle_trim_margins	ct				false
toggle_status_bar	<C-n>				false
toggle_fullscreen	f	<C-D-f>	<F11>	<F11>	false
presentation	<F5>				false
follow_link	F				false
outline	o				false
overview	O				false
confirm	<CR>				false
zoom_in	+, =	<D-=>, <D-S-=>	<C-=>, <C-S-=>, <C-kPlus>	<C-=>, <C-S-=>, <C-kPlus>	true
zoom_out	-	<D–>	<C–>, <C-kMinus>	<C–>, <C-kMinus>	true
reset_zoom	0	<D-0>	<C-0>	<C-0>	false
fit_width	a				false
fit_page	s				false
fit_height	S				false
reload_config	<C-S-r>				false
open_config		<D-,>			false
rotate_cw	r				false
rotate_ccw	R				false
goto_page_prompt	<C-g>				false
clear_search					false
highlight_selection	H				false
undo	u	<D-z>	<C-z>	<C-z>	false
redo	U	<D-S-z>	<C-y>, <C-S-z>	<C-y>, <C-S-z>	false
delete_annotation	x				false
search_matches	gm				false
show_completion	<Tab>				false
next_completion					false
prev_completion	<S-Tab>				false
copy	<C-c>	<D-c>			false
cut	<C-x>	<D-x>			false
paste	<C-v>	<D-v>			false
close	<Esc>				false
jump_forward	<C-i>	<D-]>	<A-Right>	<A-Right>	false
jump_backward	<C-o>	<D-[>	<A-Left>	<A-Left>	false
open_file_picker	<C-S-o>	<D-o>			false
show_recent_files	gr				false
save	<C-s>	<D-s>			false
print	<C-p>	<D-p>			false
help	<F1>, g?				false
keybinds					false
pan	<Space>				false
autoscroll					false
quit	q	<D-q>, <D-w>	<C-q>, <C-w>	<C-q>, <C-w>	false

Lua tables

• onon.document: path, name, extension, exists, size_bytes, and page_count.
• onon.options (alias onon.o): all entries from the configuration-options table.
• onon.theme: the theme; see Theme. Read or assign whole, or one field at a time.
• onon.themes: each built-in theme as a fresh table, such as onon.themes.birch.
• onon.cache, onon.ui, and onon.plugin: functions are listed above.

Status bar

Show or hide the status bar with onon.options.status_bar_visible. Its look comes from the theme: status_bar_style places it along the bottom or floating as pills, status_bar_padding sets its horizontal spacing and font.size its text size, and the status, status_left and status_right elements style it further. The status_bar_left and status_bar_right options are templates with these substitutions:

Placeholder	Value
{message}	Status message or active input prompt.
{page}	Current physical page, or the page range for a dual-page spread.
{label}	PDF page label, or the label range for a dual-page spread.
{total}	Total physical page count.
{mode} / {fit}	Current render mode and fit mode.
{rot} / {zoom}	Clockwise rotation in degrees and zoom as a percentage.
{dual} / {cover}	dual or single, and cover or flat.
{search}	Current match counter, such as [2/5], or empty when there is no current match.
{document}	Document filename.
{modified}	[+] while the document has unsaved edits, else empty.
{input} / {prompt}	Active input text and search prompt (/ or ?).
$$	A literal dollar sign.