gopdf 0.2.5

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

Configuration options

Assign options with gopdf.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_background	color	{20, 20, 20}	Viewer background in alternate-color mode.
alt_colors	boolean	false	Start with alternate colors enabled.
alt_foreground	color	{255, 255, 255}	UI foreground in alternate-color mode.
alt_page_background	color	{17, 17, 17}	Page background in alternate-color mode.
alt_status_bar_color	color	{20, 20, 20}	Status bar background in alternate-color mode.
anchor_position	string	"center"	Viewport anchor: center, top, or bottom.
anti_aliasing	integer	8	MuPDF antialiasing level from 0 through 8.
background	color	{220, 220, 220}	Viewer background color.
completion_max_items	integer	10	Maximum command-completion rows.
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, or manual.
foreground	color	{20, 20, 20}	UI foreground color.
highlight_background	color	{255, 224, 102}	Selection and search highlight background.
highlight_foreground	color	{0, 0, 0}	Selection and search highlight border and text.
mouse_text_select	boolean	true	Enable text selection with the left mouse button.
natural_scroll	boolean	false	Reverse mouse-wheel scrolling direction.
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.
page_background	color	{255, 255, 255}	Normal page background color.
page_cache_size	integer	16	Maximum rendered pages retained in the cache.
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.
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.
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.
spread_gap	integer	0	Horizontal spread gap; aliases page_gap_horizontal.
status_bar_color	color	{220, 220, 220}	Normal status bar background color.
status_bar_height	integer	28	Status bar height in pixels.
status_bar_left	string	"{message}"	Left status bar template.
status_bar_padding	integer	8	Horizontal status bar padding in pixels.
status_bar_right	string	"{page}/{total} {mode} fit={fit} rot={rot} {zoom}"	Right status bar template.
status_bar_visible	boolean	true	Show the status bar at startup.
ui_font_path	string	""	Path to a UI font; empty uses the built-in default.
ui_font_size	integer	14	UI font size in pixels.

Commands

Command	Description
:colors normal|alt	Set color mode
:fit width|page|manual	Set fit mode
:help	Show this command help window
:keybinds	Toggle the keybinds menu
:lua <code>	Execute Lua code inline
:mode continuous|single	Set render mode
:open <filename>	Open another PDF relative to the current document
:open_file_picker	Open the PDF file picker
:page PAGE, :p PAGE, :N	Jump to a page number or label
:quit, :q	Exit
:reload-config	Reload the config file
:recent	Open the recent-files menu
:search [-r] [-i] [-w] [-p] <text>	Search document text
:set [option[?]|option!|option=value]	Inspect or change options

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

Lua functions

Function	Description
gopdf.bind(key, action)	Bind a key sequence to an action or Lua callback.
gopdf.bind_mouse(event, action)	Bind a mouse event to an action or Lua callback.
gopdf.cache.clear()	Clear rendered-page caches.
gopdf.cache.entries()	Return the number of cached rendered pages.
gopdf.cache.limit()	Return the rendered-page cache limit.
gopdf.cache.pending()	Return the number of pending renders.
gopdf.cache.set_limit(limit)	Set the rendered-page cache limit.
gopdf.clear_pending_keys()	Clear the pending sequence, mark, and numeric count.
gopdf.command(command)	Execute a viewer command.
gopdf.current_count()	Return the pending numeric action count.
gopdf.fit_mode()	Return the current fit mode.
gopdf.fullscreen()	Return fullscreen state.
gopdf.goto_page(page)	Jump to a 1-based physical page number.
gopdf.message([text])	Get the current message or set it when text is supplied.
gopdf.mode()	Return the current input mode.
gopdf.open(path)	Open another document.
gopdf.page()	Return the current 1-based physical page number.
gopdf.page_count()	Return the document page count.
gopdf.pending_keys()	Return pending key-sequence tokens.
gopdf.pick_file([callback])	Open the native PDF picker; returns a path or invokes callback.
gopdf.recent_files([limit])	Return recent document paths.
gopdf.render_mode()	Return continuous or single render mode.
gopdf.rotation()	Return clockwise rotation in degrees.
gopdf.search(query[, backward])	Search using the same flags as :search.
gopdf.search_match_count()	Return the number of discovered search matches.
gopdf.search_match_index()	Return the current 1-based match index or nil.
gopdf.search_query()	Return the active search query.
gopdf.set_fit_mode(mode)	Set page, width, or manual fit mode.
gopdf.set_fullscreen(enabled)	Set fullscreen state.
gopdf.set_render_mode(mode)	Set continuous or single render mode.
gopdf.set_rotation(degrees)	Set clockwise rotation in degrees.
gopdf.set_status_bar_visible(visible)	Set status bar visibility.
gopdf.set_zoom(scale)	Set manual zoom scale.
gopdf.status_bar_visible()	Return status bar visibility.
gopdf.ui.close()	Close the active Lua overlay without on_close.
gopdf.ui.set_rows(rows)	Replace overlay rows.
gopdf.ui.set_selected(index)	Select a 1-based overlay row.
gopdf.ui.show(spec)	Show a searchable modal list overlay.
gopdf.ui.visible()	Return whether a Lua overlay is visible.
gopdf.unbind(key)	Remove a key binding.
gopdf.unbind_mouse(event)	Remove a mouse binding.
gopdf.zoom()	Return the current render scale.

Bindable actions

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

Action	Default keys	Countable
next_page	J, Space, <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	false
last_page	G	false
command_mode	:	false
search_prompt	/	false
search_prompt_backward	?	false
search_next	n	true
search_prev	N	true
toggle_dual_page	d	false
toggle_render_mode	m	false
toggle_alt_colors	<C-r>	false
toggle_first_page_offset	co	false
toggle_status_bar	<C-n>	false
toggle_fullscreen	f	false
outline	o	false
confirm	<CR>	false
zoom_in	+, =	true
zoom_out	-	true
reset_zoom	0	false
fit_width	w	false
fit_page	z	false
reload_config	<C-S-r>	false
rotate_cw	r	false
rotate_ccw	R	false
goto_page_prompt	<C-g>	false
clear_search		false
show_completion	<Tab>	false
next_completion		false
prev_completion	<S-Tab>	false
close	<Esc>	false
jump_forward	<C-i>	false
jump_backward	<C-o>	false
open_file_picker	<C-S-o>	false
show_recent_files	gr	false
keybinds	<F1>	false
pan		false
quit	q	false

Lua tables

• gopdf.document: path, name, extension, exists, size_bytes, and page_count.
• gopdf.status_bar: left, right, height, and visible.
• gopdf.options: all entries from the configuration-options table.
• gopdf.cache and gopdf.ui: functions are listed above.