diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.yml index 0181bafa..16871dc5 100644 --- a/.github/actions/setup/action.yml +++ b/.github/actions/setup/action.yml @@ -34,6 +34,7 @@ runs: libxkbcommon-dev \ libxkbcommon-x11-dev \ ninja-build \ + pandoc \ python3-pip \ python3-setuptools \ python3-wheel \ diff --git a/Makefile.am b/Makefile.am index acf567ef..adcda08c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -172,19 +172,52 @@ rofi_LDADD=\ $(LIBS) ## -# Manpage +# Manpages ## + +.PHONY: generate-manpage + +if FOUND_PANDOC + +generate-manpage: doc/rofi.1\ + doc/rofi-sensible-terminal.1\ + doc/rofi-theme-selector.1\ + doc/rofi-debugging.5\ + doc/rofi-dmenu.5\ + doc/rofi-keys.5\ + doc/rofi-script.5\ + doc/rofi-theme.5 + +doc/rofi.1: doc/rofi.1.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-sensible-terminal.1: doc/rofi-sensible-terminal.1.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-theme-selector.1: doc/rofi-theme-selector.1.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-debugging.5: doc/rofi-debugging.5.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-dmenu.5: doc/rofi-dmenu.5.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-keys.5: doc/rofi-keys.5.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-script.5: doc/rofi-script.5.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< +doc/rofi-theme.5: doc/rofi-theme.5.markdown + pandoc --standalone --to=man --lua-filter=$(top_srcdir)/doc/man_filter.lua -f markdown-tex_math_dollars -o ./$@ ./$< + +endif + dist_man1_MANS=\ doc/rofi.1\ - doc/rofi-theme-selector.1\ - doc/rofi-sensible-terminal.1 + doc/rofi-sensible-terminal.1\ + doc/rofi-theme-selector.1 dist_man5_MANS=\ - doc/rofi-theme.5\ doc/rofi-debugging.5\ - doc/rofi-keys.5\ doc/rofi-dmenu.5\ - doc/rofi-script.5 + doc/rofi-keys.5\ + doc/rofi-script.5\ + doc/rofi-theme.5 EXTRA_DIST += \ doc/rofi-theme.5.markdown \ @@ -254,19 +287,7 @@ EXTRA_DIST+=\ doc/default_configuration.rasi\ doc/default_theme.rasi\ Changelog -## -# Indent -## -update-manpage: $(top_srcdir)/doc/rofi-theme-selector.1.markdown $(top_srcdir)/doc/rofi.1.markdown $(top_srcdir)/doc/rofi-theme.5.markdown $(top_srcdir)/doc/rofi-script.5.markdown ${top_srcdir}/doc/rofi-sensible-terminal.1.markdown ${top_srcdir}/doc/rofi-keys.5.markdown ${top_srcdir}/doc/rofi-dmenu.5.markdown $(top_srcdir)/doc/rofi-debugging.5.markdown - go-md2man -in $(top_srcdir)/doc/rofi.1.markdown -out $(top_srcdir)/doc/rofi.1 - go-md2man -in $(top_srcdir)/doc/rofi-theme-selector.1.markdown -out $(top_srcdir)/doc/rofi-theme-selector.1 - go-md2man -in $(top_srcdir)/doc/rofi-theme.5.markdown -out $(top_srcdir)/doc/rofi-theme.5 - go-md2man -in $(top_srcdir)/doc/rofi-debugging.5.markdown -out $(top_srcdir)/doc/rofi-debugging.5 - go-md2man -in $(top_srcdir)/doc/rofi-keys.5.markdown -out $(top_srcdir)/doc/rofi-keys.5 - go-md2man -in $(top_srcdir)/doc/rofi-script.5.markdown -out $(top_srcdir)/doc/rofi-script.5 - go-md2man -in $(top_srcdir)/doc/rofi-dmenu.5.markdown -out $(top_srcdir)/doc/rofi-dmenu.5 - go-md2man -in $(top_srcdir)/doc/rofi-sensible-terminal.1.markdown -out $(top_srcdir)/doc/rofi-sensible-terminal.1 ## # Rofi test program @@ -656,6 +677,8 @@ EXTRA_DIST += \ subprojects/libgwater/wayland-server/meson.build \ subprojects/libgwater/meson.build \ subprojects/libgwater/win/meson.build \ + subprojects/libnkutils/bindings/meson.build \ + subprojects/libnkutils/core/meson.build \ subprojects/libnkutils/meson.build \ subprojects/libnkutils/meson_options.txt \ subprojects/libgwater/wayland/libgwater-wayland.h \ diff --git a/configure.ac b/configure.ac index 2b97e366..c658aed9 100644 --- a/configure.ac +++ b/configure.ac @@ -169,6 +169,13 @@ AC_ARG_ENABLE([check], AS_HELP_STRING([--disable-check], [Build with checks usin AS_IF([test "x${enable_check}" != "xno"], [ PKG_CHECK_MODULES([check],[check >= 0.11.0], [HAVE_CHECK=1]) ]) AM_CONDITIONAL([USE_CHECK], [test "x${enable_check}" != "xno" && test "$HAVE_CHECK" -eq 1]) +dnl --------------------------------------------------------------------- +dnl Build man pages +dnl --------------------------------------------------------------------- +AC_ARG_ENABLE([man], AS_HELP_STRING([--disable-man], [Build man pages (default: enabled)])) + +AS_IF([test "x$enable_man" != "xno" ], [ AC_CHECK_PROG([pandoc], pandoc, [yes])]) +AM_CONDITIONAL([FOUND_PANDOC], [test "x$pandoc" = xyes]) dnl --------------------------------------------------------------------- dnl Gets the resource compile tool path. @@ -210,6 +217,11 @@ echo "Check based tests Enabled" else echo "Check based tests Disabled" fi +if test "x${enable_man}" != "xno" && test "x$pandoc" = "xyes"; then +echo "Build man pages Enabled" +else +echo "Build man pages Disabled" +fi echo "-------------------------------------" echo "Now type 'make' to build" echo "" diff --git a/doc/README.md b/doc/README.md index 389e7a61..49814bc3 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,7 +1,7 @@ -Manpages are build using [go-md2man](https://github.com/cpuguy83/go-md2man) +Manpages are build using [pandoc](https://pandoc.org/) Manpages can be updated using the following make command: ``` -make update-manpage +make generate-manpage ``` diff --git a/doc/man_filter.lua b/doc/man_filter.lua new file mode 100644 index 00000000..eaa41cd6 --- /dev/null +++ b/doc/man_filter.lua @@ -0,0 +1,237 @@ +local Def = {} + +function Def:new(d) + -- init with empty def + if d == nil then + d = { + start_idx = nil, + end_idx = nil, + def_par = nil, + content = {}, + } + end + setmetatable(d, self) + self.__index = self + return d +end + +function Def:init(start_idx, el) + self.start_idx = start_idx + self.def_par = el +end + +function Def:append(el) + if self.start_idx ~= nil then + table.insert(self.content, el) + end +end + +function Def:stop(end_idx) + if self.start_idx == nil then + return nil + end + local out = self:new({ + start_idx = self.start_idx, + end_idx = end_idx, + def_par = self.def_par, + content = self.content, + }) + self.start_idx = nil + self.end_idx = nil + self.def_par = nil + self.content = {} + return out +end + +function Def:to_string() + return string.format("start: %d, end: %d, def_par: %s", self.start_idx, self.end_idx, self.def_par) +end + +function find_defs(doc) + local defs = {} + local idx = 0 + local def = Def:new() + + -- find defintions: + -- * start at paragraphs with `word` ... + -- * stop at next definition or next header + local filter = { + traverse = "topdown", + Para = function(el) + idx = idx + 1 + + local new_def_start = #el.content >= 1 and el.content[1].tag == "Code" + + if new_def_start then + local newd = def:stop(idx - 1) + table.insert(defs, newd) + + def:init(idx, el.content) + else + def:append(el) + end + return nil, false + end, + Block = function(el) + idx = idx + 1 + def:append(el) + -- stop exploring after one nesting level + return nil, false + end, + Header = function(el) + idx = idx + 1 + local newd = def:stop(idx - 1) + table.insert(defs, newd) + return nil, false + end, + } + + doc:walk(filter) + local newd = def:stop(idx - 1) + table.insert(defs, newd) + + return defs +end + +function convert_defs(doc, defs) + local idx = 0 + local out_blocks = {} + + local convert_defs = { + traverse = "topdown", + Block = function(el) + idx = idx + 1 + for _, d in ipairs(defs) do + if idx == d.end_idx then + local dl = pandoc.DefinitionList({ { d.def_par, { d.content } } }) + table.insert(out_blocks, dl:walk()) + return {}, false + end + if idx >= d.start_idx and idx < d.end_idx then + -- drop + return {}, false + end + end + table.insert(out_blocks, el:walk()) + return nil, false + end, + } + + doc:walk(convert_defs) + + return pandoc.Pandoc(out_blocks, doc.meta) +end + +-- for <2.17 compatibility +-- equivalent to `doc:walk(filter)` +local function walk_doc(doc, filter) + local div = pandoc.Div(doc.blocks) + local blocks = pandoc.walk_block(div, filter).content + return pandoc.Pandoc(blocks, doc.meta) +end + +local function extract_title(doc) + local title = {} + local section + local filter = { + Header = function(el) + local f = { + Str = function(el) + if el.text:find("%(1%)") ~= nil then + section = "General Commands Manual" + elseif el.text:find("%(5%)") ~= nil then + section = "File Formats Manual" + end + table.insert(title, el) + end, + Inline = function(el) + table.insert(title, el) + end, + } + if el.level == 1 then + pandoc.walk_block(el, f) + return {} -- drop + end + return nil + end, + } + + doc = walk_doc(doc, filter) + + local to_inline = function(s) + local r = {} + for w in s:gmatch("%S+") do + table.insert(r, pandoc.Str(w)) + table.insert(r, pandoc.Space()) + end + table.remove(r, #r) + return r + end + + if section ~= nil then + for _, e in ipairs({ + pandoc.Space(), + pandoc.Str("rofi"), + pandoc.Space(), + pandoc.Str("|"), + table.unpack(to_inline(section)), + }) do + table.insert(title, e) + end + end + + doc.meta = pandoc.Meta({ + title = pandoc.MetaInlines(title), + }) + + return doc +end + +local function decrement_heading(doc) + local filter = { + Header = function(el) + if el.level > 1 then + el.level = el.level - 1 + return el + end + return nil + end, + } + + doc = walk_doc(doc, filter) + return doc +end + +local function code_in_strong(doc) + local filter = { + Code = function(el) + return pandoc.Strong(el.text) + end, + } + + doc = walk_doc(doc, filter) + return doc +end + +--- Run filtering function through whole document +-- +-- * find argument definitions: paragraph starting with inline code (`-arg`) +-- * replace the paragraphs until the end of the definition with a DefinitionList +-- * extract metadata title from main heading +-- * decrement heading from 1 for better display +-- * convert inline code text to Strong as usual in man pages +function Pandoc(doc) + if PANDOC_VERSION >= pandoc.types.Version("2.17.0") then + -- 2.17 is required for topdown traversal + local defs = find_defs(doc) + doc = convert_defs(doc, defs) + end + + doc = extract_title(doc) + + doc = decrement_heading(doc) + + doc = code_in_strong(doc) + + return doc +end diff --git a/doc/meson.build b/doc/meson.build index e898a5b0..b5bb2f01 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,25 +1,52 @@ -gomd2man = find_program('go-md2man', required: false) -if gomd2man.found() +man_files = [ + 'rofi.1', + 'rofi-sensible-terminal.1', + 'rofi-theme-selector.1', + 'rofi-debugging.5', + 'rofi-dmenu.5', + 'rofi-keys.5', + 'rofi-script.5', + 'rofi-theme.5', +] + +fs = import('fs') + +pandoc = find_program('pandoc', required: false, version: '>=2.9') + +if pandoc.found() man_targets = [] - foreach f: [ - 'rofi.1', - 'rofi-theme-selector.1', - 'rofi-theme.5', - 'rofi-dmenu.5', - 'rofi-debugging.5', - 'rofi-keys.5', - 'rofi-script.5', - 'rofi-sensible-terminal.1' - ] + cp_cmds = [] + foreach f: man_files + section_number = f.split('.')[1] + install_dest = join_paths(get_option('prefix'), get_option('mandir'), 'man' + section_number) + man_targets += custom_target(f, - input: '.'.join([f, 'markdown']), + input: ['.'.join([f, 'markdown']), 'man_filter.lua'], output: f, - command: [ 'go-md2man', - '-in', files('.'.join([f,'markdown'])), - '-out', files(f) - ]) + command: [ 'pandoc', '--standalone', '--to=man', + '--lua-filter', '@INPUT1@', + '-f', 'markdown-tex_math_dollars', + '@INPUT0@', '-o', '@OUTPUT@' ], + install: true, + install_dir: install_dest, + build_by_default: true, + ) endforeach - run_target('update-manpage', command: ['true'], depends: man_targets) + + run_target('generate-manpage', command: ['true'], depends: man_targets) +else + man_missing = false + foreach f: man_files + if not fs.is_file(f) + man_missing = true + endif + endforeach + + if man_missing + warning('Man files cannot be generated and not present in source directory, they will not be installed') + else + install_man(man_files) + endif endif doxy_conf = configuration_data() diff --git a/doc/rofi-debugging.5 b/doc/rofi-debugging.5 deleted file mode 100644 index 73a934b9..00000000 --- a/doc/rofi-debugging.5 +++ /dev/null @@ -1,256 +0,0 @@ -.nh -.TH ROFI DEBUGGING 5 rofi debugging -.SH NAME -.PP -Debugging rofi. - -.PP -When reporting an issue with rofi crashing, or misbehaving. It helps to do some -small test to help pin-point the problem. - -.PP -First try disabling your custom configuration: \fB\fC-no-config\fR - -.PP -This disables the parsing of the configuration files. This runs rofi in \fIstock\fP -mode. - -.PP -If you run custom C plugins, you can disable the plugins using: \fB\fC-no-plugins\fR - -.SH Get the relevant information for an issue -.PP -Please pastebin the output of the following commands: - -.PP -.RS - -.nf -rofi -help -rofi -dump-config -rofi -dump-theme - -.fi -.RE - -.PP -\fB\fCrofi -help\fR provides us with the configuration files parsed, the exact -version, monitor layout and more useful information. - -.PP -The \fB\fCrofi -dump-config\fR and \fB\fCrofi -dump-theme\fR output gives us \fB\fCrofi\fR -interpretation of your configuration and theme. - -.PP -Please check the output for identifiable information and remove this. - -.SH Timing traces -.PP -To get a timing trace, enable the \fBTimings\fP debug domain. - -.PP -.RS - -.nf -G_MESSAGES_DEBUG=Timings rofi -show drun - -.fi -.RE - -.PP -It will show a trace with (useful) timing information at relevant points during -the execution. This will help debugging when rofi is slow to start. - -.PP -Example trace: - -.PP -.RS - -.nf -(process:14942): Timings-DEBUG: 13:47:39.335: 0.000000 (0.000000): Started -(process:14942): Timings-DEBUG: 13:47:39.335: 0.000126 (0.000126): ../source/rofi.c:main:786 -(process:14942): Timings-DEBUG: 13:47:39.335: 0.000163 (0.000037): ../source/rofi.c:main:819 -(process:14942): Timings-DEBUG: 13:47:39.336: 0.000219 (0.000056): ../source/rofi.c:main:826 Setup Locale -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001235 (0.001016): ../source/rofi.c:main:828 Collect MODI -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001264 (0.000029): ../source/rofi.c:main:830 Setup MODI -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001283 (0.000019): ../source/rofi.c:main:834 Setup mainloop -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001369 (0.000086): ../source/rofi.c:main:837 NK Bindings -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001512 (0.000143): ../source/xcb.c:display_setup:1177 Open Display -(process:14942): Timings-DEBUG: 13:47:39.337: 0.001829 (0.000317): ../source/xcb.c:display_setup:1192 Setup XCB -(process:14942): Timings-DEBUG: 13:47:39.346: 0.010650 (0.008821): ../source/rofi.c:main:844 Setup Display -(process:14942): Timings-DEBUG: 13:47:39.346: 0.010715 (0.000065): ../source/rofi.c:main:848 Setup abe -(process:14942): Timings-DEBUG: 13:47:39.350: 0.015101 (0.004386): ../source/rofi.c:main:883 Load cmd config -(process:14942): Timings-DEBUG: 13:47:39.351: 0.015275 (0.000174): ../source/rofi.c:main:907 Setup Modi -(process:14942): Timings-DEBUG: 13:47:39.351: 0.015291 (0.000016): ../source/view.c:rofi_view_workers_initialize:1922 Setup Threadpool, start -(process:14942): Timings-DEBUG: 13:47:39.351: 0.015349 (0.000058): ../source/view.c:rofi_view_workers_initialize:1945 Setup Threadpool, done -(process:14942): Timings-DEBUG: 13:47:39.367: 0.032018 (0.016669): ../source/rofi.c:main:1000 Setup late Display -(process:14942): Timings-DEBUG: 13:47:39.367: 0.032080 (0.000062): ../source/rofi.c:main:1003 Theme setup -(process:14942): Timings-DEBUG: 13:47:39.367: 0.032109 (0.000029): ../source/rofi.c:startup:668 Startup -(process:14942): Timings-DEBUG: 13:47:39.367: 0.032121 (0.000012): ../source/rofi.c:startup:677 Grab keyboard -(process:14942): Timings-DEBUG: 13:47:39.368: 0.032214 (0.000093): ../source/view.c:__create_window:701 xcb create window -(process:14942): Timings-DEBUG: 13:47:39.368: 0.032235 (0.000021): ../source/view.c:__create_window:705 xcb create gc -(process:14942): Timings-DEBUG: 13:47:39.368: 0.033136 (0.000901): ../source/view.c:__create_window:714 create cairo surface -(process:14942): Timings-DEBUG: 13:47:39.369: 0.033286 (0.000150): ../source/view.c:__create_window:723 pango cairo font setup -(process:14942): Timings-DEBUG: 13:47:39.369: 0.033351 (0.000065): ../source/view.c:__create_window:761 configure font -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045896 (0.012545): ../source/view.c:__create_window:769 textbox setup -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045944 (0.000048): ../source/view.c:__create_window:781 setup window attributes -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045955 (0.000011): ../source/view.c:__create_window:791 setup window fullscreen -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045966 (0.000011): ../source/view.c:__create_window:797 setup window name and class -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045974 (0.000008): ../source/view.c:__create_window:808 setup startup notification -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045981 (0.000007): ../source/view.c:__create_window:810 done -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045992 (0.000011): ../source/rofi.c:startup:679 Create Window -(process:14942): Timings-DEBUG: 13:47:39.381: 0.045999 (0.000007): ../source/rofi.c:startup:681 Parse ABE -(process:14942): Timings-DEBUG: 13:47:39.381: 0.046113 (0.000114): ../source/rofi.c:startup:684 Config sanity check -(process:14942): Timings-DEBUG: 13:47:39.384: 0.048229 (0.002116): ../source/dialogs/run.c:get_apps:216 start -(process:14942): Timings-DEBUG: 13:47:39.390: 0.054626 (0.006397): ../source/dialogs/run.c:get_apps:336 stop -(process:14942): Timings-DEBUG: 13:47:39.390: 0.054781 (0.000155): ../source/dialogs/drun.c:get_apps:634 Get Desktop apps (start) -(process:14942): Timings-DEBUG: 13:47:39.391: 0.055264 (0.000483): ../source/dialogs/drun.c:get_apps:641 Get Desktop apps (user dir) -(process:14942): Timings-DEBUG: 13:47:39.418: 0.082884 (0.027620): ../source/dialogs/drun.c:get_apps:659 Get Desktop apps (system dirs) -(process:14942): Timings-DEBUG: 13:47:39.418: 0.082944 (0.000060): ../source/dialogs/drun.c:get_apps_history:597 Start drun history -(process:14942): Timings-DEBUG: 13:47:39.418: 0.082977 (0.000033): ../source/dialogs/drun.c:get_apps_history:617 Stop drun history -(process:14942): Timings-DEBUG: 13:47:39.419: 0.083638 (0.000661): ../source/dialogs/drun.c:get_apps:664 Sorting done. -(process:14942): Timings-DEBUG: 13:47:39.419: 0.083685 (0.000047): ../source/view.c:rofi_view_create:1759 -(process:14942): Timings-DEBUG: 13:47:39.419: 0.083700 (0.000015): ../source/view.c:rofi_view_create:1783 Startup notification -(process:14942): Timings-DEBUG: 13:47:39.419: 0.083711 (0.000011): ../source/view.c:rofi_view_create:1786 Get active monitor -(process:14942): Timings-DEBUG: 13:47:39.420: 0.084693 (0.000982): ../source/view.c:rofi_view_refilter:1028 Filter start -(process:14942): Timings-DEBUG: 13:47:39.421: 0.085992 (0.001299): ../source/view.c:rofi_view_refilter:1132 Filter done -(process:14942): Timings-DEBUG: 13:47:39.421: 0.086090 (0.000098): ../source/view.c:rofi_view_update:982 -(process:14942): Timings-DEBUG: 13:47:39.421: 0.086123 (0.000033): ../source/view.c:rofi_view_update:1002 Background -(process:14942): Timings-DEBUG: 13:47:39.428: 0.092864 (0.006741): ../source/view.c:rofi_view_update:1008 widgets - -.fi -.RE - -.SH Debug domains -.PP -To further debug the plugin, you can get a trace with (lots of) debug -information. This debug output can be enabled for multiple parts in rofi using -the glib debug framework. Debug domains can be enabled by setting the -G_MESSAGES_DEBUG environment variable. At the time of creation of this page, -the following debug domains exist: - -.RS -.IP \(bu 2 -all: Show debug information from all domains. -.IP \(bu 2 -X11Helper: The X11 Helper functions. -.IP \(bu 2 -View: The main window view functions. -.IP \(bu 2 -Widgets.Box: The Box widget. -.IP \(bu 2 -Modes.DMenu: The dmenu mode. -.IP \(bu 2 -Modes.Run: The run mode. -.IP \(bu 2 -Modes.DRun: The desktop file run mode. -.IP \(bu 2 -Modes.Window: The window mode. -.IP \(bu 2 -Modes.Script: The script mode. -.IP \(bu 2 -Modes.Combi: The script mode. -.IP \(bu 2 -Modes.Ssh: The ssh mode. -.IP \(bu 2 -Rofi: The main application. -.IP \(bu 2 -Timings: Get timing output. -.IP \(bu 2 -Theme: Theme engine debug output. (warning lots of output). -.IP \(bu 2 -Widgets.Icon: The Icon widget. -.IP \(bu 2 -Widgets.Box: The box widget. -.IP \(bu 2 -Widgets.Container: The container widget. -.IP \(bu 2 -Widgets.Window: The window widget. -.IP \(bu 2 -Helpers.IconFetcher: Information about icon lookup. - -.RE - -.PP -For full list see \fB\fCman rofi\fR\&. - -.PP -Example: \fB\fCG_MESSAGES_DEBUG=Dialogs.DRun rofi -show drun\fR To get specific output -from the Desktop file run dialog. - -.PP -To redirect the debug output to a file (\fB\fC~/rofi.log\fR) add: - -.PP -.RS - -.nf -rofi -show drun -log ~/rofi.log - -.fi -.RE - -.PP -Specifying the logfile automatically enabled all log domains. -This can be useful when rofi is launched from a window manager. - -.SH Creating a backtrace -.PP -First make sure you compile \fBrofi\fP with debug symbols: - -.PP -.RS - -.nf -make CFLAGS="-O0 -g3" clean rofi - -.fi -.RE - -.PP -Getting a backtrace using GDB is not very handy. Because if rofi get stuck, it -grabs keyboard and mouse. So if it crashes in GDB you are stuck. The best way -to go is to enable core file. (ulimit -c unlimited in bash) then make rofi -crash. You can then load the core in GDB. - -.PP -.RS - -.nf -gdb rofi core - -.fi -.RE - -.PP -Then type inside gdb: - -.PP -.RS - -.nf -thread apply all bt - -.fi -.RE - -.PP -The output trace is useful when reporting crashes. - -.PP -Some distribution have \fB\fCsystemd-coredump\fR, this way you can easily get a -backtrace via \fB\fCcoredumpctl\fR\&. - -.SH SEE ALSO -.PP -rofi-sensible-terminal(1), dmenu(1), rofi-debugging(5), rofi-theme(5), -rofi-script(5), rofi-keys(5),rofi-theme-selector(1) - -.SH AUTHOR -.RS -.IP \(bu 2 -Qball Cow qball@blame.services -\[la]mailto:qball@blame.services\[ra] - -.RE diff --git a/doc/rofi-debugging.5.markdown b/doc/rofi-debugging.5.markdown index 229fe773..4df15d52 100644 --- a/doc/rofi-debugging.5.markdown +++ b/doc/rofi-debugging.5.markdown @@ -1,4 +1,4 @@ -# ROFI DEBUGGING 5 rofi debugging +# rofi-debugging(5) ## NAME @@ -169,7 +169,7 @@ backtrace via `coredumpctl`. ## SEE ALSO -rofi-sensible-terminal(1), dmenu(1), rofi-debugging(5), rofi-theme(5), +rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-script(5), rofi-keys(5),rofi-theme-selector(1) ## AUTHOR diff --git a/doc/rofi-dmenu.5 b/doc/rofi-dmenu.5 deleted file mode 100644 index a2cebe59..00000000 --- a/doc/rofi-dmenu.5 +++ /dev/null @@ -1,365 +0,0 @@ -.nh -.TH ROFI-DMENU 5 rofi-dmenu -.SH NAME -.PP -\fBrofi dmenu mode\fP - Rofi dmenu emulation - -.SH DESCRIPTION -.PP -To integrate \fBrofi\fP into scripts as simple selection dialogs, -\fBrofi\fP supports emulating \fBdmenu(1)\fP (A dynamic menu for X11). - -.PP -The website for \fB\fCdmenu\fR can be found here -\[la]http://tools.suckless.org/dmenu/\[ra]\&. - -.PP -\fBrofi\fP does not aim to be 100% compatible with \fB\fCdmenu\fR\&. There are simply too -many flavors of \fB\fCdmenu\fR\&. The idea is that the basic usage command-line flags -are obeyed, theme-related flags are not. Besides, \fBrofi\fP offers some extended -features (like multi-select, highlighting, message bar, extra key bindings). - -.SH BASIC CONCEPT -.PP -In \fB\fCdmenu\fR mode, \fBrofi\fP reads data from standard in, splits them into -separate entries and displays them. If the user selects a row, this is printed -out to standard out, allowing the script to process it further. - -.PP -By default separation of rows is done on new lines, making it easy to pipe the -output a one application into \fBrofi\fP and the output of rofi into the next. - -.SH USAGE -.PP -By launching \fBrofi\fP with the \fB\fC-dmenu\fR flag it will go into dmenu emulation -mode. - -.PP -.RS - -.nf -ls | rofi -dmenu - -.fi -.RE - -.SS DMENU DROP-IN REPLACEMENT -.PP -If \fB\fCargv[0]\fR (calling command) is dmenu, \fBrofi\fP will start in dmenu mode. -This way, it can be used as a drop-in replacement for dmenu. Just copy or -symlink \fBrofi\fP to dmenu in \fB\fC$PATH\fR\&. - -.PP -.RS - -.nf -ln -s /usr/bin/rofi /usr/bin/dmenu - -.fi -.RE - -.SS DMENU VS SCRIPT MODE -.PP -Script mode is used to extend \fBrofi\fP, dmenu mode is used to extend a script. -The two do share much of the same input format. Please see the -\fBrofi-script(5)\fP manpage for more information. - -.SS DMENU SPECIFIC COMMANDLINE FLAGS -.PP -A lot of these options can also be modified by the script using special input. -See the \fBrofi-script(5)\fP manpage for more information about this syntax. - -.PP -\fB\fC-sep\fR \fIseparator\fP - -.PP -Separator for \fB\fCdmenu\fR\&. Example: To show a list of 'a' to 'e' with '|' as a -separator: - -.PP -.RS - -.nf -echo "a|b|c|d|e" | rofi -sep '|' -dmenu - -.fi -.RE - -.PP -\fB\fC-p\fR \fIprompt\fP - -.PP -Specify the prompt to show in \fB\fCdmenu\fR mode. For example, select 'monkey', -a,b,c,d, or e. - -.PP -.RS - -.nf -echo "a|b|c|d|e" | rofi -sep '|' -dmenu -p "monkey" - -.fi -.RE - -.PP -Default: \fIdmenu\fP - -.PP -\fB\fC-l\fR \fInumber of lines to show\fP - -.PP -Maximum number of lines the menu may show before scrolling. - -.PP -.RS - -.nf -rofi -dmenu -l 25 - -.fi -.RE - -.PP -Default: \fI15\fP - -.PP -\fB\fC-i\fR - -.PP -Makes \fB\fCdmenu\fR searches case-insensitive - -.PP -\fB\fC-a\fR \fIX\fP - -.PP -Active row, mark \fIX\fP as active. Where \fIX\fP is a comma-separated list of -python(1)-style indices and ranges, e.g. indices start at 0, -1 refers to the -last row with -2 preceding it, ranges are left-open and right-close, and so on. -You can specify: - -.RS -.IP \(bu 2 -A single row: '5' -.IP \(bu 2 -A range of (last 3) rows: '-3:' -.IP \(bu 2 -4 rows starting from row 7: '7:11' (or in legacy notation: '7-10') -.IP \(bu 2 -A set of rows: '2,0,-9' -.IP \(bu 2 -Or any combination: '5,-3:,7:11,2,0,-9' - -.RE - -.PP -\fB\fC-u\fR \fIX\fP - -.PP -Urgent row, mark \fIX\fP as urgent. See \fB\fC-a\fR option for details. - -.PP -\fB\fC-only-match\fR - -.PP -Only return a selected item, do not allow custom entry. -This mode always returns an entry. It will not return if no matching entry is -selected. - -.PP -\fB\fC-no-custom\fR - -.PP -Only return a selected item, do not allow custom entry. -This mode returns directly when no entries given. - -.PP -\fB\fC-format\fR \fIformat\fP - -.PP -Allows the output of dmenu to be customized (N is the total number of input -entries): - -.RS -.IP \(bu 2 -\&'s' selected string -.IP \(bu 2 -\&'i' index (0 - (N-1)) -.IP \(bu 2 -\&'d' index (1 - N) -.IP \(bu 2 -\&'q' quote string -.IP \(bu 2 -\&'p' Selected string stripped from Pango markup (Needs to be a valid string) -.IP \(bu 2 -\&'f' filter string (user input) -.IP \(bu 2 -\&'F' quoted filter string (user input) - -.RE - -.PP -Default: 's' - -.PP -\fB\fC-select\fR \fIstring\fP - -.PP -Select first line that matches the given string - -.PP -\fB\fC-mesg\fR \fIstring\fP - -.PP -Add a message line below the filter entry box. Supports Pango markup. For more -information on supported markup, see -here -\[la]https://docs.gtk.org/Pango/pango_markup.html\[ra] - -.PP -\fB\fC-dump\fR - -.PP -Dump the filtered list to stdout and quit. -This can be used to get the list as \fBrofi\fP would filter it. -Use together with \fB\fC-filter\fR command. - -.PP -\fB\fC-input\fR \fIfile\fP - -.PP -Reads from \fIfile\fP instead of stdin. - -.PP -\fB\fC-password\fR - -.PP -Hide the input text. This should not be considered secure! - -.PP -\fB\fC-markup-rows\fR - -.PP -Tell \fBrofi\fP that DMenu input is Pango markup encoded, and should be rendered. -See here -\[la]https://developer.gnome.org/pygtk/stable/pango-markup-language.html\[ra] -for details about Pango markup. - -.PP -\fB\fC-multi-select\fR - -.PP -Allow multiple lines to be selected. Adds a small selection indicator to the -left of each entry. - -.PP -\fB\fC-sync\fR - -.PP -Force \fBrofi\fP mode to first read all data from stdin before showing the -selection window. This is original dmenu behavior. - -.PP -Note: the default asynchronous mode will also be automatically disabled if used -with conflicting options, -such as \fB\fC-dump\fR, \fB\fC-only-match\fR or \fB\fC-auto-select\fR\&. - -.PP -\fB\fC-window-title\fR \fItitle\fP - -.PP -Set name used for the window title. Will be shown as Rofi - \fItitle\fP - -.PP -\fB\fC-w\fR \fIwindowid\fP - -.PP -Position \fBrofi\fP over the window with the given X11 window ID. - -.PP -\fB\fC-keep-right\fR - -.PP -Set ellipsize mode to start. So, the end of the string is visible. - -.PP -\fB\fC-display-columns\fR - -.PP -A comma seperated list of columns to show. - -.PP -\fB\fC-display-column-separator\fR - -.PP -The column separator. This is a regex. - -.PP -\fIdefault\fP: '\\t' - -.PP -\fB\fC-ballot-selected-str\fR \fIstring\fP - -.PP -When multi-select is enabled, prefix this string when element is selected. - -.PP -\fIdefault\fP: "☑ " - -.PP -\fB\fC-ballot-unselected-str\fR \fIstring\fP - -.PP -When multi-select is enabled, prefix this string when element is not selected. - -.PP -\fIdefault\fP: "☐ " - -.PP -\fB\fC-ellipsize-mode\fR (start|middle|end) - -.PP -Set ellipsize mode on the listview. - -.PP -\fIdefault\fP "end" - -.SH PARSING ROW OPTIONS -.PP -Extra options for individual rows can be also set. See the \fBrofi-script(5)\fP -manpage for details; the syntax and supported features are identical. - -.SH RETURN VALUE -.RS -.IP \(bu 2 -\fB0\fP: Row has been selected accepted by user. -.IP \(bu 2 -\fB1\fP: User cancelled the selection. -.IP \(bu 2 -\fB10-28\fP: Row accepted by custom keybinding. - -.RE - -.SH SEE ALSO -.PP -rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), rofi-script(5), -rofi-theme-selector(1), ascii(7) - -.SH AUTHOR -.PP -Qball Cow qball@gmpclient.org -\[la]mailto:qball@gmpclient.org\[ra] - -.PP -Rasmus Steinke rasi@xssn.at -\[la]mailto:rasi@xssn.at\[ra] - -.PP -Morgane Glidic sardemff7+rofi@sardemff7.net -\[la]mailto:sardemff7+rofi@sardemff7.net\[ra] - -.PP -Original code based on work by: Sean Pringle sean.pringle@gmail.com -\[la]mailto:sean.pringle@gmail.com\[ra] - -.PP -For a full list of authors, check the AUTHORS file. diff --git a/doc/rofi-dmenu.5.markdown b/doc/rofi-dmenu.5.markdown index 3d19eb98..27e484b3 100644 --- a/doc/rofi-dmenu.5.markdown +++ b/doc/rofi-dmenu.5.markdown @@ -1,4 +1,4 @@ -# ROFI-DMENU 5 rofi-dmenu +# rofi-dmenu(5) ## NAME diff --git a/doc/rofi-keys.5 b/doc/rofi-keys.5 deleted file mode 100644 index 78237118..00000000 --- a/doc/rofi-keys.5 +++ /dev/null @@ -1,676 +0,0 @@ -.nh -.TH ROFI-KEYS 5 rofi-keys -.SH NAME -.PP -\fBrofi keys\fP - Rofi Key and Mouse bindings - -.SH DESCRIPTION -.PP -\fBrofi\fP supports overriding of any of it key and mouse binding. - -.SH Setting binding -.PP -Bindings can be done on the commandline (-{bindingname}): - -.PP -.RS - -.nf -rofi -show run -kb-accept-entry 'Control+Shift+space' - -.fi -.RE - -.PP -or via the configuration file: - -.PP -.RS - -.nf -configuration { - kb-accept-entry: "Control+Shift+space"; -} - -.fi -.RE - -.PP -The key can be set by its name (see above) or its keycode: - -.PP -.RS - -.nf -configuration { - kb-accept-entry: "Control+Shift+[65]"; -} - -.fi -.RE - -.PP -An easy way to look up keycode is xev(1). - -.PP -Multiple keys can be specified for an action as a comma separated list: - -.PP -.RS - -.nf -configuration { - kb-accept-entry: "Control+Shift+space,Return"; -} - -.fi -.RE - -.PP -By Default \fBrofi\fP reacts on pressing, to act on the release of all keys -prepend the binding with \fB\fC!\fR: - -.PP -.RS - -.nf -configuration { - kb-accept-entry: "!Control+Shift+space,Return"; -} - -.fi -.RE - -.SH Unsetting a binding -.PP -To unset a binding, pass an empty string. - -.PP -.RS - -.nf -configuration { - kb-clear-line: ""; -} - -.fi -.RE - -.SH Keyboard Bindings -.SS \fBkb-primary-paste\fP: -.PP -Paste primary selection - -.PP -\fBDefault\fP: Control+V,Shift+Insert - -.SS \fBkb-secondary-paste\fP -.PP -Paste clipboard - -.PP -\fBDefault\fP: Control+v,Insert - -.SS \fBkb-secondary-copy\fP -.PP -Copy current selection to clipboard - -.PP -\fBDefault\fP: Control+c - -.SS \fBkb-clear-line\fP -.PP -Clear input line - -.PP -\fBDefault\fP: Control+w - -.SS \fBkb-move-front\fP -.PP -Beginning of line - -.PP -\fBDefault\fP: Control+a - -.SS \fBkb-move-end\fP -.PP -End of line - -.PP -\fBDefault\fP: Control+e - -.SS \fBkb-move-word-back\fP -.PP -Move back one word - -.PP -\fBDefault\fP: Alt+b,Control+Left - -.SS \fBkb-move-word-forward\fP -.PP -Move forward one word - -.PP -\fBDefault\fP: Alt+f,Control+Right - -.SS \fBkb-move-char-back\fP -.PP -Move back one char - -.PP -\fBDefault\fP: Left,Control+b - -.SS \fBkb-move-char-forward\fP -.PP -Move forward one char - -.PP -\fBDefault\fP: Right,Control+f - -.SS \fBkb-remove-word-back\fP -.PP -Delete previous word - -.PP -\fBDefault\fP: Control+Alt+h,Control+BackSpace - -.SS \fBkb-remove-word-forward\fP -.PP -Delete next word - -.PP -\fBDefault\fP: Control+Alt+d - -.SS \fBkb-remove-char-forward\fP -.PP -Delete next char - -.PP -\fBDefault\fP: Delete,Control+d - -.SS \fBkb-remove-char-back\fP -.PP -Delete previous char - -.PP -\fBDefault\fP: BackSpace,Shift+BackSpace,Control+h - -.SS \fBkb-remove-to-eol\fP -.PP -Delete till the end of line - -.PP -\fBDefault\fP: Control+k - -.SS \fBkb-remove-to-sol\fP -.PP -Delete till the start of line - -.PP -\fBDefault\fP: Control+u - -.SS \fBkb-accept-entry\fP -.PP -Accept entry - -.PP -\fBDefault\fP: Control+j,Control+m,Return,KP_Enter - -.SS \fBkb-accept-custom\fP -.PP -Use entered text as command (in ssh/run modes) - -.PP -\fBDefault\fP: Control+Return - -.SS \fBkb-accept-custom-alt\fP -.PP -Use entered text as command (in ssh/run modes) - -.PP -\fBDefault\fP: Control+Shift+Return - -.SS \fBkb-accept-alt\fP -.PP -Use alternate accept command. - -.PP -\fBDefault\fP: Shift+Return - -.SS \fBkb-delete-entry\fP -.PP -Delete entry from history - -.PP -\fBDefault\fP: Shift+Delete - -.SS \fBkb-mode-next\fP -.PP -Switch to the next mode. - -.PP -\fBDefault\fP: Shift+Right,Control+Tab - -.SS \fBkb-mode-previous\fP -.PP -Switch to the previous mode. - -.PP -\fBDefault\fP: Shift+Left,Control+ISO_Left_Tab - -.SS \fBkb-mode-complete\fP -.PP -Start completion for mode. - -.PP -\fBDefault\fP: Control+l - -.SS \fBkb-row-left\fP -.PP -Go to the previous column - -.PP -\fBDefault\fP: Control+Page_Up - -.SS \fBkb-row-right\fP -.PP -Go to the next column - -.PP -\fBDefault\fP: Control+Page_Down - -.SS \fBkb-row-up\fP -.PP -Select previous entry - -.PP -\fBDefault\fP: Up,Control+p - -.SS \fBkb-row-down\fP -.PP -Select next entry - -.PP -\fBDefault\fP: Down,Control+n - -.SS \fBkb-row-tab\fP -.PP -Go to next row, if one left, accept it, if no left next mode. - -.PP -\fBDefault\fP: - -.SS \fBkb-element-next\fP -.PP -Go to next row. - -.PP -\fBDefault\fP: Tab - -.SS \fBkb-element-prev\fP -.PP -Go to previous row. - -.PP -\fBDefault\fP: ISO_Left_Tab - -.SS \fBkb-page-prev\fP -.PP -Go to the previous page - -.PP -\fBDefault\fP: Page_Up - -.SS \fBkb-page-next\fP -.PP -Go to the next page - -.PP -\fBDefault\fP: Page_Down - -.SS \fBkb-row-first\fP -.PP -Go to the first entry - -.PP -\fBDefault\fP: Home,KP_Home - -.SS \fBkb-row-last\fP -.PP -Go to the last entry - -.PP -\fBDefault\fP: End,KP_End - -.SS \fBkb-row-select\fP -.PP -Set selected item as input text - -.PP -\fBDefault\fP: Control+space - -.SS \fBkb-screenshot\fP -.PP -Take a screenshot of the rofi window - -.PP -\fBDefault\fP: Alt+S - -.SS \fBkb-ellipsize\fP -.PP -Toggle between ellipsize modes for displayed data - -.PP -\fBDefault\fP: Alt+period - -.SS \fBkb-toggle-case-sensitivity\fP -.PP -Toggle case sensitivity - -.PP -\fBDefault\fP: grave,dead_grave - -.SS \fBkb-toggle-sort\fP -.PP -Toggle filtered menu sort - -.PP -\fBDefault\fP: Alt+grave - -.SS \fBkb-cancel\fP -.PP -Quit rofi - -.PP -\fBDefault\fP: Escape,Control+g,Control+bracketleft - -.SS \fBkb-custom-1\fP -.PP -Custom keybinding 1 - -.PP -\fBDefault\fP: Alt+1 - -.SS \fBkb-custom-2\fP -.PP -Custom keybinding 2 - -.PP -\fBDefault\fP: Alt+2 - -.SS \fBkb-custom-3\fP -.PP -Custom keybinding 3 - -.PP -\fBDefault\fP: Alt+3 - -.SS \fBkb-custom-4\fP -.PP -Custom keybinding 4 - -.PP -\fBDefault\fP: Alt+4 - -.SS \fBkb-custom-5\fP -.PP -Custom Keybinding 5 - -.PP -\fBDefault\fP: Alt+5 - -.SS \fBkb-custom-6\fP -.PP -Custom keybinding 6 - -.PP -\fBDefault\fP: Alt+6 - -.SS \fBkb-custom-7\fP -.PP -Custom Keybinding 7 - -.PP -\fBDefault\fP: Alt+7 - -.SS \fBkb-custom-8\fP -.PP -Custom keybinding 8 - -.PP -\fBDefault\fP: Alt+8 - -.SS \fBkb-custom-9\fP -.PP -Custom keybinding 9 - -.PP -\fBDefault\fP: Alt+9 - -.SS \fBkb-custom-10\fP -.PP -Custom keybinding 10 - -.PP -\fBDefault\fP: Alt+0 - -.SS \fBkb-custom-11\fP -.PP -Custom keybinding 11 - -.PP -\fBDefault\fP: Alt+exclam - -.SS \fBkb-custom-12\fP -.PP -Custom keybinding 12 - -.PP -\fBDefault\fP: Alt+at - -.SS \fBkb-custom-13\fP -.PP -Custom keybinding 13 - -.PP -\fBDefault\fP: Alt+numbersign - -.SS \fBkb-custom-14\fP -.PP -Custom keybinding 14 - -.PP -\fBDefault\fP: Alt+dollar - -.SS \fBkb-custom-15\fP -.PP -Custom keybinding 15 - -.PP -\fBDefault\fP: Alt+percent - -.SS \fBkb-custom-16\fP -.PP -Custom keybinding 16 - -.PP -\fBDefault\fP: Alt+dead_circumflex - -.SS \fBkb-custom-17\fP -.PP -Custom keybinding 17 - -.PP -\fBDefault\fP: Alt+ampersand - -.SS \fBkb-custom-18\fP -.PP -Custom keybinding 18 - -.PP -\fBDefault\fP: Alt+asterisk - -.SS \fBkb-custom-19\fP -.PP -Custom Keybinding 19 - -.PP -\fBDefault\fP: Alt+parenleft - -.SS \fBkb-select-1\fP -.PP -Select row 1 - -.PP -\fBDefault\fP: Super+1 - -.SS \fBkb-select-2\fP -.PP -Select row 2 - -.PP -\fBDefault\fP: Super+2 - -.SS \fBkb-select-3\fP -.PP -Select row 3 - -.PP -\fBDefault\fP: Super+3 - -.SS \fBkb-select-4\fP -.PP -Select row 4 - -.PP -\fBDefault\fP: Super+4 - -.SS \fBkb-select-5\fP -.PP -Select row 5 - -.PP -\fBDefault\fP: Super+5 - -.SS \fBkb-select-6\fP -.PP -Select row 6 - -.PP -\fBDefault\fP: Super+6 - -.SS \fBkb-select-7\fP -.PP -Select row 7 - -.PP -\fBDefault\fP: Super+7 - -.SS \fBkb-select-8\fP -.PP -Select row 8 - -.PP -\fBDefault\fP: Super+8 - -.SS \fBkb-select-9\fP -.PP -Select row 9 - -.PP -\fBDefault\fP: Super+9 - -.SS \fBkb-select-10\fP -.PP -Select row 10 - -.PP -\fBDefault\fP: Super+0 - -.SS \fBkb-entry-history-up\fP -.PP -Go up in the entry history. - -.PP -\fBDefault\fP: Control+Up - -.SS \fBkb-entry-history-down\fP -.PP -Go down in the entry history. - -.PP -\fBDefault\fP: Control+Down - -.SH Mouse Bindings -.SS \fBml-row-left\fP -.PP -Go to the previous column - -.PP -\fBDefault\fP: ScrollLeft - -.SS \fBml-row-right\fP -.PP -Go to the next column - -.PP -\fBDefault\fP: ScrollRight - -.SS \fBml-row-up\fP -.PP -Select previous entry - -.PP -\fBDefault\fP: ScrollUp - -.SS \fBml-row-down\fP -.PP -Select next entry - -.PP -\fBDefault\fP: ScrollDown - -.SS \fBme-select-entry\fP -.PP -Select hovered row - -.PP -\fBDefault\fP: MousePrimary - -.SS \fBme-accept-entry\fP -.PP -Accept hovered row - -.PP -\fBDefault\fP: MouseDPrimary - -.SS \fBme-accept-custom\fP -.PP -Accept hovered row with custom action - -.PP -\fBDefault\fP: Control+MouseDPrimary - -.SH SEE ALSO -.PP -rofi(1), rofi-sensible-terminal(1), rofi-theme(5), rofi-script(5) - -.SH AUTHOR -.PP -Qball Cow qball@gmpclient.org -\[la]mailto:qball@gmpclient.org\[ra] - -.PP -Rasmus Steinke rasi@xssn.at -\[la]mailto:rasi@xssn.at\[ra] - -.PP -Morgane Glidic sardemff7+rofi@sardemff7.net -\[la]mailto:sardemff7+rofi@sardemff7.net\[ra] - -.PP -Original code based on work by: Sean Pringle sean.pringle@gmail.com -\[la]mailto:sean.pringle@gmail.com\[ra] - -.PP -For a full list of authors, check the AUTHORS file. diff --git a/doc/rofi-keys.5.markdown b/doc/rofi-keys.5.markdown index 98d68ea1..b6e264df 100644 --- a/doc/rofi-keys.5.markdown +++ b/doc/rofi-keys.5.markdown @@ -1,4 +1,4 @@ -# ROFI-KEYS 5 rofi-keys +# rofi-keys(5) ## NAME @@ -63,481 +63,481 @@ configuration { ## Keyboard Bindings -### **kb-primary-paste**: +`kb-primary-paste` Paste primary selection -**Default**: Control+V,Shift+Insert +Default: Control+V,Shift+Insert -### **kb-secondary-paste** +`kb-secondary-paste` Paste clipboard -**Default**: Control+v,Insert +Default: Control+v,Insert -### **kb-secondary-copy** +`kb-secondary-copy` Copy current selection to clipboard -**Default**: Control+c +Default: Control+c -### **kb-clear-line** +`kb-clear-line` Clear input line -**Default**: Control+w +Default: Control+w -### **kb-move-front** +`kb-move-front` Beginning of line -**Default**: Control+a +Default: Control+a -### **kb-move-end** +`kb-move-end` End of line -**Default**: Control+e +Default: Control+e -### **kb-move-word-back** +`kb-move-word-back` Move back one word -**Default**: Alt+b,Control+Left +Default: Alt+b,Control+Left -### **kb-move-word-forward** +`kb-move-word-forward` Move forward one word -**Default**: Alt+f,Control+Right +Default: Alt+f,Control+Right -### **kb-move-char-back** +`kb-move-char-back` Move back one char -**Default**: Left,Control+b +Default: Left,Control+b -### **kb-move-char-forward** +`kb-move-char-forward` Move forward one char -**Default**: Right,Control+f +Default: Right,Control+f -### **kb-remove-word-back** +`kb-remove-word-back` Delete previous word -**Default**: Control+Alt+h,Control+BackSpace +Default: Control+Alt+h,Control+BackSpace -### **kb-remove-word-forward** +`kb-remove-word-forward` Delete next word -**Default**: Control+Alt+d +Default: Control+Alt+d -### **kb-remove-char-forward** +`kb-remove-char-forward` Delete next char -**Default**: Delete,Control+d +Default: Delete,Control+d -### **kb-remove-char-back** +`kb-remove-char-back` Delete previous char -**Default**: BackSpace,Shift+BackSpace,Control+h +Default: BackSpace,Shift+BackSpace,Control+h -### **kb-remove-to-eol** +`kb-remove-to-eol` Delete till the end of line -**Default**: Control+k +Default: Control+k -### **kb-remove-to-sol** +`kb-remove-to-sol` Delete till the start of line -**Default**: Control+u +Default: Control+u -### **kb-accept-entry** +`kb-accept-entry` Accept entry -**Default**: Control+j,Control+m,Return,KP\_Enter +Default: Control+j,Control+m,Return,KP\_Enter -### **kb-accept-custom** +`kb-accept-custom` Use entered text as command (in ssh/run modes) -**Default**: Control+Return +Default: Control+Return -### **kb-accept-custom-alt** +`kb-accept-custom-alt` Use entered text as command (in ssh/run modes) -**Default**: Control+Shift+Return +Default: Control+Shift+Return -### **kb-accept-alt** +`kb-accept-alt` Use alternate accept command. -**Default**: Shift+Return +Default: Shift+Return -### **kb-delete-entry** +`kb-delete-entry` Delete entry from history -**Default**: Shift+Delete +Default: Shift+Delete -### **kb-mode-next** +`kb-mode-next` Switch to the next mode. -**Default**: Shift+Right,Control+Tab +Default: Shift+Right,Control+Tab -### **kb-mode-previous** +`kb-mode-previous` Switch to the previous mode. -**Default**: Shift+Left,Control+ISO\_Left\_Tab +Default: Shift+Left,Control+ISO\_Left\_Tab -### **kb-mode-complete** +`kb-mode-complete` Start completion for mode. -**Default**: Control+l +Default: Control+l -### **kb-row-left** +`kb-row-left` Go to the previous column -**Default**: Control+Page\_Up +Default: Control+Page\_Up -### **kb-row-right** +`kb-row-right` Go to the next column -**Default**: Control+Page\_Down +Default: Control+Page\_Down -### **kb-row-up** +`kb-row-up` Select previous entry -**Default**: Up,Control+p +Default: Up,Control+p -### **kb-row-down** +`kb-row-down` Select next entry -**Default**: Down,Control+n +Default: Down,Control+n -### **kb-row-tab** +`kb-row-tab` Go to next row, if one left, accept it, if no left next mode. -**Default**: +Default: -### **kb-element-next** +`kb-element-next` Go to next row. -**Default**: Tab +Default: Tab -### **kb-element-prev** +`kb-element-prev` Go to previous row. -**Default**: ISO\_Left\_Tab +Default: ISO\_Left\_Tab -### **kb-page-prev** +`kb-page-prev` Go to the previous page -**Default**: Page\_Up +Default: Page\_Up -### **kb-page-next** +`kb-page-next` Go to the next page -**Default**: Page\_Down +Default: Page\_Down -### **kb-row-first** +`kb-row-first` Go to the first entry -**Default**: Home,KP\_Home +Default: Home,KP\_Home -### **kb-row-last** +`kb-row-last` Go to the last entry -**Default**: End,KP\_End +Default: End,KP\_End -### **kb-row-select** +`kb-row-select` Set selected item as input text -**Default**: Control+space +Default: Control+space -### **kb-screenshot** +`kb-screenshot` Take a screenshot of the rofi window -**Default**: Alt+S +Default: Alt+S -### **kb-ellipsize** +`kb-ellipsize` Toggle between ellipsize modes for displayed data -**Default**: Alt+period +Default: Alt+period -### **kb-toggle-case-sensitivity** +`kb-toggle-case-sensitivity` Toggle case sensitivity -**Default**: grave,dead\_grave +Default: grave,dead\_grave -### **kb-toggle-sort** +`kb-toggle-sort` Toggle filtered menu sort -**Default**: Alt+grave +Default: Alt+grave -### **kb-cancel** +`kb-cancel` Quit rofi -**Default**: Escape,Control+g,Control+bracketleft +Default: Escape,Control+g,Control+bracketleft -### **kb-custom-1** +`kb-custom-1` Custom keybinding 1 -**Default**: Alt+1 +Default: Alt+1 -### **kb-custom-2** +`kb-custom-2` Custom keybinding 2 -**Default**: Alt+2 +Default: Alt+2 -### **kb-custom-3** +`kb-custom-3` Custom keybinding 3 -**Default**: Alt+3 +Default: Alt+3 -### **kb-custom-4** +`kb-custom-4` Custom keybinding 4 -**Default**: Alt+4 +Default: Alt+4 -### **kb-custom-5** +`kb-custom-5` Custom Keybinding 5 -**Default**: Alt+5 +Default: Alt+5 -### **kb-custom-6** +`kb-custom-6` Custom keybinding 6 -**Default**: Alt+6 +Default: Alt+6 -### **kb-custom-7** +`kb-custom-7` Custom Keybinding 7 -**Default**: Alt+7 +Default: Alt+7 -### **kb-custom-8** +`kb-custom-8` Custom keybinding 8 -**Default**: Alt+8 +Default: Alt+8 -### **kb-custom-9** +`kb-custom-9` Custom keybinding 9 -**Default**: Alt+9 +Default: Alt+9 -### **kb-custom-10** +`kb-custom-10` Custom keybinding 10 -**Default**: Alt+0 +Default: Alt+0 -### **kb-custom-11** +`kb-custom-11` Custom keybinding 11 -**Default**: Alt+exclam +Default: Alt+exclam -### **kb-custom-12** +`kb-custom-12` Custom keybinding 12 -**Default**: Alt+at +Default: Alt+at -### **kb-custom-13** +`kb-custom-13` Custom keybinding 13 -**Default**: Alt+numbersign +Default: Alt+numbersign -### **kb-custom-14** +`kb-custom-14` Custom keybinding 14 -**Default**: Alt+dollar +Default: Alt+dollar -### **kb-custom-15** +`kb-custom-15` Custom keybinding 15 -**Default**: Alt+percent +Default: Alt+percent -### **kb-custom-16** +`kb-custom-16` Custom keybinding 16 -**Default**: Alt+dead\_circumflex +Default: Alt+dead\_circumflex -### **kb-custom-17** +`kb-custom-17` Custom keybinding 17 -**Default**: Alt+ampersand +Default: Alt+ampersand -### **kb-custom-18** +`kb-custom-18` Custom keybinding 18 -**Default**: Alt+asterisk +Default: Alt+asterisk -### **kb-custom-19** +`kb-custom-19` Custom Keybinding 19 -**Default**: Alt+parenleft +Default: Alt+parenleft -### **kb-select-1** +`kb-select-1` Select row 1 -**Default**: Super+1 +Default: Super+1 -### **kb-select-2** +`kb-select-2` Select row 2 -**Default**: Super+2 +Default: Super+2 -### **kb-select-3** +`kb-select-3` Select row 3 -**Default**: Super+3 +Default: Super+3 -### **kb-select-4** +`kb-select-4` Select row 4 -**Default**: Super+4 +Default: Super+4 -### **kb-select-5** +`kb-select-5` Select row 5 -**Default**: Super+5 +Default: Super+5 -### **kb-select-6** +`kb-select-6` Select row 6 -**Default**: Super+6 +Default: Super+6 -### **kb-select-7** +`kb-select-7` Select row 7 -**Default**: Super+7 +Default: Super+7 -### **kb-select-8** +`kb-select-8` Select row 8 -**Default**: Super+8 +Default: Super+8 -### **kb-select-9** +`kb-select-9` Select row 9 -**Default**: Super+9 +Default: Super+9 -### **kb-select-10** +`kb-select-10` Select row 10 -**Default**: Super+0 +Default: Super+0 -### **kb-entry-history-up** +`kb-entry-history-up` Go up in the entry history. -**Default**: Control+Up +Default: Control+Up -### **kb-entry-history-down** +`kb-entry-history-down` Go down in the entry history. -**Default**: Control+Down +Default: Control+Down ## Mouse Bindings -### **ml-row-left** +`ml-row-left` Go to the previous column -**Default**: ScrollLeft +Default: ScrollLeft -### **ml-row-right** +`ml-row-right` Go to the next column -**Default**: ScrollRight +Default: ScrollRight -### **ml-row-up** +`ml-row-up` Select previous entry -**Default**: ScrollUp +Default: ScrollUp -### **ml-row-down** +`ml-row-down` Select next entry -**Default**: ScrollDown +Default: ScrollDown -### **me-select-entry** +`me-select-entry` Select hovered row -**Default**: MousePrimary +Default: MousePrimary -### **me-accept-entry** +`me-accept-entry` Accept hovered row -**Default**: MouseDPrimary +Default: MouseDPrimary -### **me-accept-custom** +`me-accept-custom` Accept hovered row with custom action -**Default**: Control+MouseDPrimary +Default: Control+MouseDPrimary ## SEE ALSO diff --git a/doc/rofi-script.5 b/doc/rofi-script.5 deleted file mode 100644 index 6b0c2126..00000000 --- a/doc/rofi-script.5 +++ /dev/null @@ -1,279 +0,0 @@ -.nh -.TH ROFI-SCRIPT 5 rofi-script -.SH NAME -.PP -\fBrofi script mode\fP - Rofi format for scriptable mode. - -.SH DESCRIPTION -.PP -\fBrofi\fP supports modes that use simple scripts in the background to generate a -list and process the result from user actions. This provide a simple interface -to make simple extensions to rofi. - -.SH USAGE -.PP -To specify a script mode, set a mode with the following syntax: -"{name}:{executable}" - -.PP -For example: - -.PP -.RS - -.nf -rofi -show fb -modes "fb:file_browser.sh" - -.fi -.RE - -.PP -The name should be unique. - -.SH API -.PP -Rofi calls the executable without arguments on startup. This should generate a -list of options, separated by a newline (\fB\fC\\n\fR) (This can be changed by the -script). If the user selects an option, rofi calls the executable with the text -of that option as the first argument. If the script returns no entries, rofi -quits. - -.PP -A simple script would be: - -.PP -.RS - -.nf -#!/usr/bin/env bash - -if [ x"$@" = x"quit" ] -then - exit 0 -fi -echo "reload" -echo "quit" - - -.fi -.RE - -.PP -This shows two entries, reload and quit. When the quit entry is selected, rofi -closes. - -.SH Environment -.PP -Rofi sets the following environment variable when executing the script: - -.SS \fB\fCROFI_RETV\fR -.PP -An integer number with the current state: - -.RS -.IP \(bu 2 -\fB0\fP: Initial call of script. -.IP \(bu 2 -\fB1\fP: Selected an entry. -.IP \(bu 2 -\fB2\fP: Selected a custom entry. -.IP \(bu 2 -\fB10-28\fP: Custom keybinding 1-19 ( need to be explicitly enabled by script ). - -.RE - -.SS \fB\fCROFI_INFO\fR -.PP -Environment get set when selected entry get set with the property value of the -'info' row option, if set. - -.SS \fB\fCROFI_DATA\fR -.PP -Environment get set when script sets \fB\fCdata\fR option in header. - -.SH Passing mode options -.PP -Extra options, like setting the prompt, can be set by the script. Extra options -are lines that start with a NULL character (\fB\fC\\0\fR) followed by a key, separator -(\fB\fC\\x1f\fR) and value. - -.PP -For example to set the prompt: - -.PP -.RS - -.nf - echo -en "\\0prompt\\x1fChange prompt\\n" - -.fi -.RE - -.PP -The following extra options exists: - -.RS -.IP \(bu 2 -\fBprompt\fP: Update the prompt text. -.IP \(bu 2 -\fBmessage\fP: Update the message text. -.IP \(bu 2 -\fBmarkup-rows\fP: If 'true' renders markup in the row. -.IP \(bu 2 -\fBurgent\fP: Mark rows as urgent. (for syntax see the urgent option in -dmenu mode) -.IP \(bu 2 -\fBactive\fP: Mark rows as active. (for syntax see the active option in -dmenu mode) -.IP \(bu 2 -\fBdelim\fP: Set the delimiter for for next rows. Default is '\\n' and -this option should finish with this. Only call this on first call of script, -it is remembered for consecutive calls. -.IP \(bu 2 -\fBno-custom\fP: If set to 'true'; only accept listed entries, ignore custom -input. -.IP \(bu 2 -\fBuse-hot-keys\fP: If set to true, it enabled the Custom keybindings for -script. Warning this breaks the normal rofi flow. -.IP \(bu 2 -\fBkeep-selection\fP: If set, the selection is not moved to the first entry, -but the current position is maintained. The filter is cleared. -.IP \(bu 2 -\fBnew-selection\fP: If \fB\fCkeep-selection\fR is set, this allows you to override -the selected entry (absolute position). -.IP \(bu 2 -\fBdata\fP: Passed data to the next execution of the script via -\fBROFI_DATA\fP\&. -.IP \(bu 2 -\fBtheme\fP: Small theme snippet to f.e. change the background color of -a widget. - -.RE - -.PP -The \fBtheme\fP property cannot change the interface while running, it is only -usable for small changes in, for example background color, of widgets that get -updated during display like the row color of the listview. - -.SH Parsing row options -.PP -Extra options for individual rows can be set. The extra option can be specified -following the same syntax as mode option, but following the entry. - -.PP -For example: - -.PP -.RS - -.nf - echo -en "aap\\0icon\\x1ffolder\\n" - -.fi -.RE - -.PP -The following options are supported: - -.RS -.IP \(bu 2 -\fBicon\fP: Set the icon for that row. -.IP \(bu 2 -\fBdisplay\fP: Replace the displayed string. (Original string will still be used for filtering) -.IP \(bu 2 -\fBmeta\fP: Specify invisible search terms used for filtering. -.IP \(bu 2 -\fBnonselectable\fP: If true the row cannot activated. -.IP \(bu 2 -\fBpermantent\fP: If true the row always shows, independent of filter. -.IP \(bu 2 -\fBinfo\fP: Info that, on selection, gets placed in the \fB\fCROFI_INFO\fR -environment variable. This entry does not get searched for filtering. -.IP \(bu 2 -\fBurgent\fP: Set urgent flag on entry (true/false) -.IP \(bu 2 -\fBactive\fP: Set active flag on entry (true/false) - -.RE - -.PP -multiple entries can be passed using the \fB\fC\\x1f\fR separator. - -.PP -.RS - -.nf - echo -en "aap\\0icon\\x1ffolder\\x1finfo\\x1ftest\\n" - -.fi -.RE - -.SH Executing external program -.PP -If you want to launch an external program from the script, you need to make -sure it is launched in the background. If not rofi will wait for its output (to -display). - -.PP -In bash the best way to do this is using \fB\fCcoproc\fR\&. - -.PP -.RS - -.nf - coproc ( myApp > /dev/null 2>&1 ) - -.fi -.RE - -.SH DASH shell -.PP -If you use the \fB\fCdash\fR shell for your script, take special care with how dash -handles escaped values for the separators. See issue #1201 on github. - -.SH Script locations -.PP -To specify a script there are the following options: - -.RS -.IP \(bu 2 -Specify an absolute path to the script. -.IP \(bu 2 -The script is executable and located in your $PATH - -.RE - -.PP -Scripts located in the following location are loaded on startup: - -.RS -.IP \(bu 2 -The script is in \fB\fC$XDG_CONFIG_PATH/rofi/scripts/\fR, this is usually -\fB\fC~/.config/rofi/scripts/\fR\&. - -.RE - -.SH SEE ALSO -.PP -rofi(1), rofi-sensible-terminal(1), dmenu(1), rofi-theme(5), -rofi-theme-selector(1) - -.SH AUTHOR -.PP -Qball Cow qball@gmpclient.org -\[la]mailto:qball@gmpclient.org\[ra] - -.PP -Rasmus Steinke rasi@xssn.at -\[la]mailto:rasi@xssn.at\[ra] - -.PP -Morgane Glidic sardemff7+rofi@sardemff7.net -\[la]mailto:sardemff7+rofi@sardemff7.net\[ra] - -.PP -Original code based on work by: Sean Pringle sean.pringle@gmail.com -\[la]mailto:sean.pringle@gmail.com\[ra] - -.PP -For a full list of authors, check the AUTHORS file. diff --git a/doc/rofi-script.5.markdown b/doc/rofi-script.5.markdown index 65bb318d..53a463d2 100644 --- a/doc/rofi-script.5.markdown +++ b/doc/rofi-script.5.markdown @@ -1,4 +1,4 @@ -# ROFI-SCRIPT 5 rofi-script +# rofi-script(5) ## NAME diff --git a/doc/rofi-sensible-terminal.1 b/doc/rofi-sensible-terminal.1 deleted file mode 100644 index dd67f0fd..00000000 --- a/doc/rofi-sensible-terminal.1 +++ /dev/null @@ -1,73 +0,0 @@ -.nh -.TH rofi-sensible-terminal 1 rofi-sensible-terminal -.SH NAME -.PP -\fBrofi-sensible-terminal\fP - launches $TERMINAL with fallbacks - -.SH SYNOPSIS -.PP -rofi-sensible-terminal [arguments] - -.SH DESCRIPTION -.PP -rofi-sensible-terminal is invoked in the rofi default config to start a terminal. This -wrapper script is necessary since there is no distribution-independent terminal launcher -(but for example Debian has x-terminal-emulator). Distribution packagers are responsible for -shipping this script in a way which is appropriate for the distribution. - -.PP -It tries to start one of the following (in that order): - -.RS -.IP \(bu 2 -\fB\fC$TERMINAL\fR (this is a non-standard variable) -.IP \(bu 2 -x-terminal-emulator -.IP \(bu 2 -urxvt -.IP \(bu 2 -rxvt -.IP \(bu 2 -st -.IP \(bu 2 -terminology -.IP \(bu 2 -qterminal -.IP \(bu 2 -Eterm -.IP \(bu 2 -aterm -.IP \(bu 2 -uxterm -.IP \(bu 2 -xterm -.IP \(bu 2 -roxterm -.IP \(bu 2 -xfce4-terminal.wrapper -.IP \(bu 2 -mate-terminal -.IP \(bu 2 -lxterminal -.IP \(bu 2 -konsole -.IP \(bu 2 -alacritty -.IP \(bu 2 -kitty -.IP \(bu 2 -wezterm - -.RE - -.SH SEE ALSO -.PP -rofi(1) - -.SH AUTHORS -.PP -Dave Davenport and contributors - -.PP -Copied script from i3: -Michael Stapelberg and contributors diff --git a/doc/rofi-sensible-terminal.1.markdown b/doc/rofi-sensible-terminal.1.markdown index dbab0f0f..1406299d 100644 --- a/doc/rofi-sensible-terminal.1.markdown +++ b/doc/rofi-sensible-terminal.1.markdown @@ -1,4 +1,4 @@ -# rofi-sensible-terminal 1 rofi-sensible-terminal +# rofi-sensible-terminal(1) ## NAME diff --git a/doc/rofi-theme-selector.1 b/doc/rofi-theme-selector.1 deleted file mode 100644 index f0d31d6e..00000000 --- a/doc/rofi-theme-selector.1 +++ /dev/null @@ -1,46 +0,0 @@ -.nh -.TH rofi-theme-selector 1 rofi-theme-selector -.SH NAME -.PP -\fBrofi-theme-selector\fP - Preview and apply themes for \fBrofi\fP - -.SH DESCRIPTION -.PP -\fBrofi-theme-selector\fP is a bash/rofi script to preview and apply themes for -\fBrofi\fP\&. It's part of any installation of \fBrofi\fP\&. - -.SH USAGE -.SS Running rofi-theme-selector -.PP -\fBrofi-theme-selector\fP shows a list of all available themes in a \fBrofi\fP -window. It lets you preview each theme with the Enter key and apply the theme -to your \fBrofi\fP configuration file with Alt+a. - -.SH Theme directories -.PP -\fBrofi-theme-selector\fP searches the following directories for themes: - -.RS -.IP \(bu 2 -${PREFIX}/share/rofi/themes -.IP \(bu 2 -$XDG_CONFIG_HOME/rofi/themes -.IP \(bu 2 -$XDG_DATA_HOME/share/rofi/themes - -.RE - -.PP -${PREFIX} reflects the install location of rofi. In most cases this will be -"/usr". -$XDG_CONFIG_HOME is normally unset. Default path is "$HOME/.config". -$XDG_DATA_HOME is normally unset. Default path is "$HOME/.local/share". - -.SH SEE ALSO -.PP -rofi(1) - -.SH AUTHORS -.PP -Qball Cow qball@gmpclient.org -Rasmus Steinke rasi@xssn.at diff --git a/doc/rofi-theme-selector.1.markdown b/doc/rofi-theme-selector.1.markdown index f52f31c7..1fa8b6fe 100644 --- a/doc/rofi-theme-selector.1.markdown +++ b/doc/rofi-theme-selector.1.markdown @@ -1,4 +1,4 @@ -# rofi-theme-selector 1 rofi-theme-selector +# rofi-theme-selector(1) ## NAME diff --git a/doc/rofi-theme.5 b/doc/rofi-theme.5 deleted file mode 100644 index 7a4708fa..00000000 --- a/doc/rofi-theme.5 +++ /dev/null @@ -1,2449 +0,0 @@ -.nh -.TH ROFI-THEME 5 rofi-theme -.SH NAME -.PP -\fBrofi-theme\fP - Rofi theme format files - -.SH Getting started with theming -.PP -The easiest way to get started theming rofi is by modifying your existing theme. - -.PP -Themes can be modified/tweaked by adding theming elements to the end of the\\ -config file. The default location of this file is \fB\fC~/.config/rofi/config.rasi\fR, -if the file does not exists, you can create it. - -.PP -A basic config: - -.PP -.RS - -.nf -configuration { - modes: [ combi ]; - combi-modes: [ window, drun, run ]; -} - -@theme "gruvbox-light" - -/* Insert theme modifications after this */ - -.fi -.RE - -.PP -For example if we want to change the \fB\fCType to filter\fR text in the entry box we -append the following: - -.PP -.RS - -.nf -entry { - placeholder: "Type here"; -} - -.fi -.RE - -.PP -In the above section, \fB\fCentry\fR indicates the widget, \fB\fCplaceholder\fR is the -property we want to modify and we set it to the string \fB\fC"Type here"\fR\&. To find -the commonly available widgets in rofi, see the 'Basic structure' section. - -.PP -To change the mouse over cursor to a pointer, add: - -.PP -.RS - -.nf -entry { - placeholder: "Type here"; - cursor: pointer; -} - -.fi -.RE - -.PP -For the next modification, we want to add the icon after each text element and -increase the size. First we start by modifying the \fB\fCelement\fR widget: - -.PP -.RS - -.nf - -element { - orientation: horizontal; - children: [ element-text, element-icon ]; - spacing: 5px; -} - - -.fi -.RE - -.PP -Resulting in the following packing: - -.PP -.RS - -.nf -┌─────────────────────────────────────────────────────────────────────┐ -│ element │ -│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │ -│ │element─text │ │ element─icon │ │ -│ └─────────────────────────────────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ - -.fi -.RE - -.PP -The \fB\fCelement\fR (container) widget hold each entry in the \fB\fClistview\fR, we add the -two pre-defined children in the order we want to show. We also specify the -packing direction (\fB\fCorientation\fR) and the spacing between the children -(\fB\fCspacing\fR). We specify the space between the two children in absolute pixels -(\fB\fCpx\fR). - -.PP -To increase the icon-size, we need to modify the \fB\fCelement-icon\fR widget. - -.PP -.RS - -.nf -element-icon { - size: 2.5em; -} - -.fi -.RE - -.PP -.RS - -.nf -┌─────────────────────────────────────────────────────────────────────┐ -│ element │ -│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │ -│ │element─text │ │ element │ │ -│ │ │ │ ─ │ │ -│ │ │ │ icon │ │ -│ └─────────────────────────────────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ - -.fi -.RE - -.PP -In this example we specify the size in the em -\[la]https://www.w3.org/Style/LieBos3e/em\[ra] unit. - -.PP -Now lets change the text color of both the \fB\fCentry\fR and the \fB\fCelement-text\fR -widget to red and background to blue. - -.PP -.RS - -.nf -entry, element-text { - text-color: red; - background-color: rgb(0,0,255); -} - -.fi -.RE - -.PP -Here we use two different methods of writing down the color, for \fB\fCtext-color\fR -we used a named color, for \fB\fCbackground-color\fR we specify it in \fB\fCrgb\fR\&. -We also specify the property for multiple widgets by passing a comma separated -list of widget names. - -.PP -If you want to center the text relative to the icon, we can set this: - -.PP -.RS - -.nf -element-text { - vertical-align: 0.5; -} - -.fi -.RE - -.PP -.RS - -.nf -┌─────────────────────────────────────────────────────────────────────┐ -│ element │ -│ ┌─────────────────────────────────────────────┐ ┌─────────────────┐ │ -│ │ │ │ element │ │ -│ │element-text │ │ ─ │ │ -│ │ │ │ icon │ │ -│ └─────────────────────────────────────────────┘ └─────────────────┘ │ -└─────────────────────────────────────────────────────────────────────┘ - -.fi -.RE - -.PP -We can also specify the color and width of the cursor. You could, for example, -create a crimson block cursor like this: - -.PP -.RS - -.nf -entry { - cursor-color: rgb(220,20,60); - cursor-width: 8px; -} - -.fi -.RE - -.PP -By default, the \fB\fCcursor-color\fR will be the same as the \fB\fCtext-color\fR\&. The -\fB\fCcursor-width\fR will always default to 2 pixels. - -.PP -If you want to see the complete theme, including the modification you can run: - -.PP -.RS - -.nf -rofi -dump-theme - -.fi -.RE - -.SH Default theme loading -.PP -By default, rofi loads the default theme. This theme is \fBalways\fP loaded. -The default configuration contains: - -.PP -.RS - -.nf -@theme "default" - -.fi -.RE - -.PP -To unload the default theme, and load another theme, add the \fB\fC@theme\fR statement -to your \fB\fCconfig.rasi\fR file. - -.PP -If you have a theme loaded via \fB\fC@theme\fR or use the default theme, you can tweak -it by adding overriding elements at the end of your \fB\fCconfig.rasi\fR file. - -.PP -For the difference between \fB\fC@import\fR and \fB\fC@theme\fR see the \fB\fCMultiple file -handling\fR section in this manpage. - -.PP -To see the default theme, run the following command: - -.PP -.RS - -.nf -rofi -no-config -dump-theme - -.fi -.RE - -.SH Description -.PP -The need for a new theme format was motivated by the fact that the way rofi -handled widgets has changed. From a very static drawing of lines and text to a -nice structured form of packing widgets. This change made it possible to -provide a more flexible theme framework. The old theme format and config file -are not flexible enough to expose these options in a user-friendly way. -Therefore, a new file format has been created, replacing the old one. - -.SH Format specification -.SH Encoding -.PP -The encoding of the file is UTF-8. Both unix (\fB\fC\\n\fR) and windows (\fB\fC\\r\\n\fR) -newlines format are supported. But unix is preferred. - -.SH Comments -.PP -C and C++ file comments are supported. - -.RS -.IP \(bu 2 -Anything after \fB\fC//\fR and before a newline is considered a comment. -.IP \(bu 2 -Everything between \fB\fC/*\fR and \fB\fC*/\fR is a comment, this comment can span -multiple lines. - -.RE - -.PP -Comments can be nested and the C comments can be inline. - -.PP -The following is valid: - -.PP -.RS - -.nf -// Magic comment. -property: /* comment */ value; - -.fi -.RE - -.PP -However, this is not: - -.PP -.RS - -.nf -prop/*comment*/erty: value; - -.fi -.RE - -.SH White space -.PP -White space and newlines, like comments, are ignored by the parser. - -.PP -This: - -.PP -.RS - -.nf -property: name; - -.fi -.RE - -.PP -Is identical to: - -.PP -.RS - -.nf - property : -name - -; - -.fi -.RE - -.SH File extension -.PP -The preferred file extension for the new theme format is \fBrasi\fP\&. This is an -abbreviation for \fBr\fPofi \fBa\fPdvanced \fBs\fPtyle \fBi\fPnformation. If a theme -file is split over multiple files, include files can have the: \fBrasinc\fP -extension. - -.SH Basic Structure -.PP -Each element has a section with defined properties. Global properties can be -defined in section \fB\fC* { }\fR\&. Sub-section names begin with an optional hash -symbol \fB\fC#\fR\&. - -.PP -It is advised to define the \fIglobal properties section\fP on top of the file to -make inheritance of properties clearer. - -.PP -.RS - -.nf -/* Global properties section */ -* { - // list of properties -} - -/* Element theme section. */ -{element path} { - // list of properties -} -{elements... } { - // list of properties -} - -.fi -.RE - -.PP -If there are multiple sections with the same name, they are merged. Duplicate -properties are overwritten and the last parsed entry kept. - -.SH Global properties section -.PP -A theme can have one or more global properties sections. If there is more than -one, they will be merged. - -.PP -The global properties section denotes the defaults for each element. -Each property of this section can be referenced with \fB\fC@{identifier}\fR -(See Properties section) - -.PP -A global properties section is indicated with a \fB\fC*\fR as element path. - -.SH Element theme section -.PP -A theme can have multiple element theme sections. - -.PP -The element path can consist of multiple names separated by whitespace or dots. -Each element may contain any number of letters, numbers and \fB\fC-\fR\&'s. -The first element in the element path can optionally start with a \fB\fC#\fR (for -historic reasons). Multiple elements can be specified by a \fB\fC,\fR\&. - -.PP -This is a valid element name: - -.PP -.RS - -.nf -element normal.normal { - background-color: blue; -} -button { - background-color: blue; -} - -.fi -.RE - -.PP -And is identical to: - -.PP -.RS - -.nf -element normal normal, button { - background-color: blue; -} - -.fi -.RE - -.PP -Each section inherits the global properties. Properties can be explicitly -inherited from their parent with the \fB\fCinherit\fR keyword. -In the following example: - -.PP -.RS - -.nf -window { - a: 1; - b: 2; - children: [ mainbox ]; -} -mainbox { - a: inherit; - b: 4; - c: 8; -} - -.fi -.RE - -.PP -The element \fB\fCmainbox\fR will have the following set of properties (if \fB\fCmainbox\fR -is a child of \fB\fCwindow\fR): - -.PP -.RS - -.nf -a: 1; -b: 4; -c: 8; - -.fi -.RE - -.PP -If multiple sections are defined with the same name, they are merged by the -parser. If multiple properties with the same name are defined in one section, -the last encountered property is used. - -.SH Properties Format -.PP -The properties in a section consist of: - -.PP -.RS - -.nf -{identifier}: {value}; - -.fi -.RE - -.PP -Both fields are mandatory for a property. - -.PP -The \fB\fCidentifier\fR names the specified property. Identifiers can consist of any -combination of numbers, letters and '-'. It must not contain any whitespace. -The structure of the \fB\fCvalue\fR defines the type of the property. The current -parser does not define or enforce a certain type of a particular \fB\fCidentifier\fR\&. -When used, values with the wrong type that cannot be converted are ignored. - -.PP -The current theme format supports different types: - -.RS -.IP \(bu 2 -a string -.IP \(bu 2 -an integer number -.IP \(bu 2 -a fractional number -.IP \(bu 2 -a boolean value -.IP \(bu 2 -a color -.IP \(bu 2 -image -.IP \(bu 2 -text style -.IP \(bu 2 -line style -.IP \(bu 2 -a distance -.IP \(bu 2 -a padding -.IP \(bu 2 -a border -.IP \(bu 2 -a position -.IP \(bu 2 -a reference -.IP \(bu 2 -an orientation -.IP \(bu 2 -a cursor -.IP \(bu 2 -a list of keywords -.IP \(bu 2 -an array of values -.IP \(bu 2 -an environment variable -.IP \(bu 2 -Inherit - -.RE - -.PP -Some of these types are a combination of other types. - -.SS String -.RS -.IP \(bu 2 -Format: \fB\fC(["'])[:print:]+\\1\fR - -.RE - -.PP -Strings are always surrounded by double (\fB\fC"\fR) or single (\fB\fC\&'\fR, apostrophe) quotes. Between -the quotes there can be any printable character. - -.PP -For example: - -.PP -.RS - -.nf -font: "Awasome 12"; - -.fi -.RE - -.PP -The string must be valid UTF-8, special characters can be escaped: - -.PP -.RS - -.nf -text { content: "Line one\\n\\tIndented line two 'Quoted text'"; } -text { content: 'Line one\\n\\tIndented line two "Quoted text"'; } -text { content: "Line one\\n\\tIndented line two \\"Quoted text\\""; } - -.fi -.RE - -.PP -The following special characters can be escaped: \fB\fC\\b\fR, \fB\fC\\f\fR, \fB\fC\\n\fR, \fB\fC\\r\fR, \fB\fC\\t\fR, \fB\fC\\v\fR, \fB\fC\\\fR, -\fB\fC"\fR and \fB\fC\&'\fR (double quotes inside single-quotes or in reverse don't need escape). - -.SS Integer -.RS -.IP \(bu 2 -Format: \fB\fC[-+]?[:digit:]+\fR - -.RE - -.PP -An integer may contain any number. - -.PP -For examples: - -.PP -.RS - -.nf -lines: 12; - -.fi -.RE - -.SS Real -.RS -.IP \(bu 2 -Format: \fB\fC[-+]?[:digit:]+(\\.[:digit:]+)?\fR - -.RE - -.PP -A real is an integer with an optional fraction. - -.PP -For example: - -.PP -.RS - -.nf -real: 3.4; - -.fi -.RE - -.PP -The following is not valid: \fB\fC\&.3\fR, \fB\fC3.\fR or scientific notation: \fB\fC3.4e-3\fR\&. - -.SS Boolean -.RS -.IP \(bu 2 -Format: \fB\fC(true|false)\fR - -.RE - -.PP -Boolean value is either \fB\fCtrue\fR or \fB\fCfalse\fR\&. This is case-sensitive. - -.PP -For example: - -.PP -.RS - -.nf -dynamic: false; - -.fi -.RE - -.SS Image -.PP -\fBrofi\fP support a limited set of background-image formats. - -.RS -.IP \(bu 2 -Format: url("path to image"); -.IP \(bu 2 -Format: url("path to image", scale); -where scale is: none, both, width, height -.IP \(bu 2 -Format: linear-gradient(stop color,stop1, color, stop2 color, ...); -.IP \(bu 2 -Format: linear-gradient(to direction, stop color,stop1, color, stop2 color, -...); where direction is: top,left,right,bottom. -.IP \(bu 2 -Format: linear-gradient(angle, stop color,stop1, color, stop2 color, ...); -Angle in deg,rad,grad (as used in color). - -.RE - -.PP -Where the \fB\fCpath\fR is a string, and \fB\fCstop\fR color is of type color. - -.SS Color -.PP -\fBrofi\fP supports the color formats as specified in the CSS standard (1,2,3 and -some of CSS 4) - -.RS -.IP \(bu 2 -Format: \fB\fC#{HEX}{3}\fR (rgb) -.IP \(bu 2 -Format: \fB\fC#{HEX}{4}\fR (rgba) -.IP \(bu 2 -Format: \fB\fC#{HEX}{6}\fR (rrggbb) -.IP \(bu 2 -Format: \fB\fC#{HEX}{8}\fR (rrggbbaa) -.IP \(bu 2 -Format: \fB\fCrgb[a]({INTEGER},{INTEGER},{INTEGER}[, {PERCENTAGE}])\fR -.IP \(bu 2 -Format: \fB\fCrgb[a]({INTEGER}%,{INTEGER}%,{INTEGER}%[, {PERCENTAGE}])\fR -.IP \(bu 2 -Format: \fB\fChsl[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])\fR -.IP \(bu 2 -Format: \fB\fChwb[a]( {ANGLE}, {PERCENTAGE}, {PERCENTAGE} [, {PERCENTAGE}])\fR -.IP \(bu 2 -Format: \fB\fCcmyk( {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE}, {PERCENTAGE} [, -{PERCENTAGE} ])\fR -.IP \(bu 2 -Format: \fB\fC{named-color} [ / {PERCENTAGE} ]\fR - -.RE - -.PP -The white-space format proposed in CSS4 is also supported. - -.PP -The different values are: - -.RS -.IP \(bu 2 -\fB\fC{HEX}\fR is a hexadecimal number ('0-9a-f' case insensitive). -.IP \(bu 2 -\fB\fC{INTEGER}\fR value can be between 0 and 255 or 0-100 when representing -percentage. -.IP \(bu 2 -\fB\fC{ANGLE}\fR is the angle on the color wheel, can be in \fB\fCdeg\fR, \fB\fCrad\fR, \fB\fCgrad\fR -or \fB\fCturn\fR\&. When no unit is specified, degrees is assumed. -.IP \(bu 2 -\fB\fC{PERCENTAGE}\fR can be between 0-1.0, or 0%-100% -.IP \(bu 2 -\fB\fC{named-color}\fR is one of the following colors:AliceBlue, AntiqueWhite, Aqua, Aquamarine, Azure, Beige, Bisque, Black, -BlanchedAlmond, Blue, BlueViolet, Brown, BurlyWood, CadetBlue, Chartreuse, -Chocolate, Coral, CornflowerBlue, Cornsilk, Crimson, Cyan, DarkBlue, -DarkCyan, DarkGoldenRod, DarkGray, DarkGrey, DarkGreen, DarkKhaki, -DarkMagenta, DarkOliveGreen, DarkOrange, DarkOrchid, DarkRed, DarkSalmon, -DarkSeaGreen, DarkSlateBlue, DarkSlateGray, DarkSlateGrey, DarkTurquoise, -DarkViolet, DeepPink, DeepSkyBlue, DimGray, DimGrey, DodgerBlue, FireBrick, -FloralWhite, ForestGreen, Fuchsia, Gainsboro, GhostWhite, Gold, GoldenRod, -Gray, Grey, Green, GreenYellow, HoneyDew, HotPink, IndianRed, Indigo, -Ivory, Khaki, Lavender, LavenderBlush, LawnGreen, LemonChiffon, LightBlue, -LightCoral, LightCyan, LightGoldenRodYellow, LightGray, LightGrey, -LightGreen, LightPink, LightSalmon, LightSeaGreen, LightSkyBlue, -LightSlateGray, LightSlateGrey, LightSteelBlue, LightYellow, Lime, -LimeGreen, Linen, Magenta, Maroon, MediumAquaMarine, MediumBlue, -MediumOrchid, MediumPurple, MediumSeaGreen, MediumSlateBlue, -MediumSpringGreen, MediumTurquoise, MediumVioletRed, MidnightBlue, -MintCream, MistyRose, Moccasin, NavajoWhite, Navy, OldLace, Olive, -OliveDrab, Orange, OrangeRed, Orchid, PaleGoldenRod, PaleGreen, -PaleTurquoise, PaleVioletRed, PapayaWhip, PeachPuff, Peru, Pink, Plum, -PowderBlue, Purple, RebeccaPurple, Red, RosyBrown, RoyalBlue, SaddleBrown, -Salmon, SandyBrown, SeaGreen, SeaShell, Sienna, Silver, SkyBlue, SlateBlue, -SlateGray, SlateGrey, Snow, SpringGreen, SteelBlue, Tan, Teal, Thistle, -Tomato, Turquoise, Violet, Wheat, White, WhiteSmoke, Yellow, -YellowGreen,transparent - -.RE - -.PP -For example: - -.PP -.RS - -.nf -background-color: #FF0000; -border-color: rgba(0,0,1, 0.5); -text-color: SeaGreen; - -.fi -.RE - -.PP -or - -.PP -.RS - -.nf -background-color: transparent; -text-color: Black; - -.fi -.RE - -.SS Text style -.RS -.IP \(bu 2 -Format: \fB\fC(bold|italic|underline|strikethrough|none)\fR - -.RE - -.PP -Text style indicates how the highlighted text is emphasized. \fB\fCNone\fR indicates -that no emphasis should be applied. - -.RS -.IP \(bu 2 -\fB\fCbold\fR: make the text thicker then the surrounding text. -.IP \(bu 2 -\fB\fCitalic\fR: put the highlighted text in script type (slanted). -.IP \(bu 2 -\fB\fCunderline\fR: put a line under the text. -.IP \(bu 2 -\fB\fCstrikethrough\fR: put a line through the text. - -.RE - -.PP -The following options are available on pango 1.50.0 and up: - -.RS -.IP \(bu 2 -\fB\fCuppercase\fR: Uppercase the text. -.IP \(bu 2 -\fB\fClowercase\fR: Lowercase the text. - -.RE - -.PP -The following option is disabled as pango crashes on this if there is eel -upsizing or wrapping. This will be re-enabled once fixed: - -.RS -.IP \(bu 2 -\fB\fCcapitalize\fR: Capitalize the text. - -.RE - -.SS Line style -.RS -.IP \(bu 2 -Format: \fB\fC(dash|solid)\fR - -.RE - -.PP -Indicates how a line should be drawn. -It currently supports: -- \fB\fCdash\fR: a dashed line, where the gap is the same width as the dash -- \fB\fCsolid\fR: a solid line - -.SS Distance -.RS -.IP \(bu 2 -Format: \fB\fC{Integer}px\fR -.IP \(bu 2 -Format: \fB\fC{Real}em\fR -.IP \(bu 2 -Format: \fB\fC{Real}ch\fR -.IP \(bu 2 -Format: \fB\fC{Real}%\fR -.IP \(bu 2 -Format: \fB\fC{Real}mm\fR - -.RE - -.PP -A distance can be specified in 3 different units: - -.RS -.IP \(bu 2 -\fB\fCpx\fR: Screen pixels. -.IP \(bu 2 -\fB\fCem\fR: Relative to text height. -.IP \(bu 2 -\fB\fCch\fR: Relative to width of a single number. -.IP \(bu 2 -\fB\fCmm\fR: Actual size in millimeters (based on dpi). -.IP \(bu 2 -\fB\fC%\fR: Percentage of the \fBmonitor\fP size. - -.RE - -.PP -Distances used in the horizontal direction use the monitor width. Distances in -the vertical direction use the monitor height. -For example: - -.PP -.RS - -.nf - padding: 10%; - -.fi -.RE - -.PP -On a full-HD (1920x1080) monitor, it defines a padding of 192 pixels on the left -and right side and 108 pixels on the top and bottom. - -.SS Calculating sizes -.PP -Rofi supports some maths in calculating sizes. For this it uses the CSS syntax: - -.PP -.RS - -.nf -width: calc( 100% - 37px ); - -.fi -.RE - -.PP -.RS - -.nf -width: calc( 20% min 512 ); - -.fi -.RE - -.PP -It supports the following operations: - -.RS -.IP \(bu 2 -\fB\fC+\fR : Add -.IP \(bu 2 -\fB\fC-\fR : Subtract -.IP \(bu 2 -\fB\fC/\fR : Divide -.IP \(bu 2 -\fB\fC-\fR : Multiply -.IP \(bu 2 -\fB\fCmodulo\fR : Modulo -.IP \(bu 2 -\fB\fCmin\fR : Minimum of lvalue or rvalue; -.IP \(bu 2 -\fB\fCmax\fR : Maximum of lvalue or rvalue; -.IP \(bu 2 -\fB\fCfloor\fR : Round down lvalue to the next multiple of rvalue -.IP \(bu 2 -\fB\fCceil\fR : Round up lvalue to the next multiple of rvalue -.IP \(bu 2 -\fB\fCround\fR : Round lvalue to the next multiple of rvalue - -.RE - -.PP -It uses the C precedence ordering. - -.SS Padding -.RS -.IP \(bu 2 -Format: \fB\fC{Integer}\fR -.IP \(bu 2 -Format: \fB\fC{Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance} {Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance} {Distance} {Distance}\fR - -.RE - -.PP -If no unit is specified, pixels are assumed. - -.PP -The different number of fields in the formats are parsed like: - -.RS -.IP \(bu 2 -1 field: \fB\fCall\fR -.IP \(bu 2 -2 fields: \fB\fCtop&bottom\fR \fB\fCleft&right\fR -.IP \(bu 2 -3 fields: \fB\fCtop\fR, \fB\fCleft&right\fR, \fB\fCbottom\fR -.IP \(bu 2 -4 fields: \fB\fCtop\fR, \fB\fCright\fR, \fB\fCbottom\fR, \fB\fCleft\fR - -.RE - -.SS Border -.RS -.IP \(bu 2 -Format: \fB\fC{Integer}\fR -.IP \(bu 2 -Format: \fB\fC{Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance} {Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Distance} {Distance} {Distance}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Line style}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Line style} {Distance} {Line style}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line -style}\fR -.IP \(bu 2 -Format: \fB\fC{Distance} {Line style} {Distance} {Line style} {Distance} {Line -style} {Distance} {Line style}\fR - -.RE - -.PP -Borders are identical to padding, except that each distance field has a line -style property. - -.PP -.RS - -.PP -When no unit is specified, pixels are assumed. - -.RE - -.SS Position -.PP -Indicate a place on the window/monitor. - -.PP -.RS - -.nf -┌─────────────┬─────────────┬─────────────┐ -│ north west │ north │ north east │ -├─────────────┼─────────────┼─────────────┤ -│ west │ center │ east │ -├─────────────┼─────────────┼─────────────┤ -│ south west │ south │ south east │ -└─────────────┴─────────────┴─────────────┘ - -.fi -.RE - -.RS -.IP \(bu 2 -Format: \fB\fC(center|east|north|west|south|north east|north west|south west|south -east)\fR - -.RE - -.SS Visibility -.PP -It is possible to hide widgets: - -.PP -.RS - -.nf -inputbar { - enabled: false; -} - -.fi -.RE - -.SS Reference -.RS -.IP \(bu 2 -Format: \fB\fC@{PROPERTY NAME}\fR - -.RE - -.PP -A reference can point to another reference. Currently, the maximum number of -redirects is 20. A property always refers to another property. It cannot be -used for a subpart of the property. For example, this is not valid: - -.PP -.RS - -.nf -highlight: bold @pink; - -.fi -.RE - -.PP -But this is: - -.PP -.RS - -.nf -* { - myhigh: bold #FAA; -} - -window { - highlight: @myhigh; -} - -.fi -.RE - -.RS -.IP \(bu 2 -Format: \fB\fCvar(PROPERTY NAME, DEFAULT)\fR - -.RE - -.PP -A reference can point to another reference. Currently, the maximum number of -redirects is 20. A property always refers to another property. It cannot be -used for a subpart of the property. - -.PP -Example: - -.PP -.RS - -.nf -window { - width: var( width, 30%); -} - -.fi -.RE - -.PP -If the property \fB\fCwidth\fR is set globally (\fB\fC*{}\fR) that value is used, if the -property \fB\fCwidth\fR is not set, the default value is used. - -.SS Orientation -.RS -.IP \(bu 2 -Format: \fB\fC(horizontal|vertical)\fR - -.RE - -.PP -Specify the orientation of the widget. - -.SS Cursor -.RS -.IP \(bu 2 -Format: \fB\fC(default|pointer|text)\fR - -.RE - -.PP -Specify the type of mouse cursor that is set when the mouse pointer is over the -widget. - -.SS List of keywords -.RS -.IP \(bu 2 -Format: \fB\fC[ keyword, keyword ]\fR - -.RE - -.PP -A list starts with a '[' and ends with a ']'. The entries in the list are -comma-separated. The \fB\fCkeyword\fR in the list refers to an widget name. - -.SS List of values -.RS -.IP \(bu 2 -Format: \fB\fC[ value, value, ... ]\fR - -.RE - -.PP -An list starts with a '[' and ends with a ']'. The entries in the list are -comma-separated. - -.SS Environment variable -.RS -.IP \(bu 2 -Format: \fB\fC${:alnum:}\fR - -.RE - -.PP -This will parse the environment variable as the property value. (that then can -be any of the above types). The environment variable should be an alphanumeric -string without white-space. - -.PP -.RS - -.nf -* { - background-color: ${BG}; -} - -.fi -.RE - -.RS -.IP \(bu 2 -Format: \fB\fCenv(ENVIRONMENT, default)\fR - -.RE - -.PP -This will parse the environment variable as the property value. (that then can -be any of the above types). The environment variable should be an alphanumeric -string without white-space. If the environment value is not found, the default -value is used. - -.PP -.RS - -.nf -window { - width: env(WIDTH, 40%); -} - -.fi -.RE - -.PP -If environment WIDTH is set, then that value is parsed, otherwise the default -value (\fB\fC40%\fR). - -.SS Inherit -.RS -.IP \(bu 2 -Format: \fB\fCinherit\fR - -.RE - -.PP -Inherits the property from its parent widget. - -.PP -.RS - -.nf -mainbox { - border-color: inherit; -} - -.fi -.RE - -.SH Elements paths -.PP -Element paths exists of two parts, the first part refers to the actual widget -by name. Some widgets have an extra state. - -.PP -For example: - -.PP -.RS - -.nf -element selected { -} - -.fi -.RE - -.PP -Here \fB\fCelement selected\fR is the name of the widget, \fB\fCselected\fR is the state of -the widget. - -.PP -The difference between dots and spaces is purely cosmetic. These are all the -same: - -.PP -.RS - -.nf -element .selected { - -element.selected { -} -element selected { -} - -.fi -.RE - -.SS Supported element paths -.SS Base widgets -.PP -The default widgets available in \fBrofi\fP and the default hierarchic: - -.RS -.IP \(bu 2 -\fB\fCwindow\fR -.RS -.IP \(bu 2 -\fB\fCoverlay\fR: the overlay widget. -.IP \(bu 2 -\fB\fCmainbox\fR: The mainbox box. -.IP \(bu 2 -\fB\fCinputbar\fR: The input bar box. -.RS -.IP \(bu 2 -\fB\fCbox\fR: the horizontal @box packing the widgets -.RS -.IP \(bu 2 -\fB\fCcase-indicator\fR: the case/sort indicator @textbox -.IP \(bu 2 -\fB\fCprompt\fR: the prompt @textbox -.IP \(bu 2 -\fB\fCentry\fR: the main entry @textbox -.IP \(bu 2 -\fB\fCnum-rows\fR: Shows the total number of rows. -.IP \(bu 2 -\fB\fCnum-filtered-rows\fR: Shows the total number of rows after -filtering. -.IP \(bu 2 -\fB\fCtextbox-current-entry\fR: Shows the text of the currently selected -entry. -.IP \(bu 2 -\fB\fCicon-current-entry\fR: Shows the icon of the currently selected -entry. - -.RE - - -.RE - -.IP \(bu 2 -\fB\fClistview\fR: The listview. -.RS -.IP \(bu 2 -\fB\fCscrollbar\fR: the listview scrollbar -.IP \(bu 2 -\fB\fCelement\fR: a box in the listview holding the entries -.RS -.IP \(bu 2 -\fB\fCelement-icon\fR: the widget in the listview's entry showing the -(optional) icon -.IP \(bu 2 -\fB\fCelement-index\fR: the widget in the listview's entry -keybindable index (1,2,3..0) -.IP \(bu 2 -\fB\fCelement-text\fR: the widget in the listview's entry showing the -text. - -.RE - - -.RE - -.IP \(bu 2 -\fB\fCmode-switcher\fR: the main horizontal @box packing the buttons. -.RS -.IP \(bu 2 -\fB\fCbutton\fR: the buttons @textbox for each mode - -.RE - -.IP \(bu 2 -\fB\fCmessage\fR: The container holding the textbox. -.RS -.IP \(bu 2 -\fB\fCtextbox\fR: the message textbox - -.RE - - -.RE - - -.RE - -.PP -Note that these path names match the default theme. Themes that provide a -custom layout will have different elements, and structure. - -.SS State -.PP -State: State of widget - -.PP -Optional flag(s) indicating state of the widget, used for theming. - -.PP -These are appended after the name or class of the widget. - -.SS Example -.PP -\fB\fCbutton selected.normal { }\fR - -.PP -\fB\fCelement selected.urgent { }\fR - -.PP -Currently only the entrybox and scrollbar have states: - -.SS Entrybox -.PP -\fB\fC{visible modifier}.{state}\fR - -.PP -Where \fB\fCvisible modifier\fR can be: -- normal: no modification -- selected: the entry is selected/highlighted by user -- alternate: the entry is at an alternating row (uneven row) - -.PP -Where \fB\fCstate\fR is: -- normal: no modification -- urgent: this entry is marked urgent -- active: this entry is marked active - -.PP -These can be mixed. - -.PP -Example: - -.PP -.RS - -.nf -nametotextbox selected.active { - background-color: #003642; - text-color: #008ed4; -} - -.fi -.RE - -.PP -Sets all selected textboxes marked active to the given text and background -color. Note that a state modifies the original element, it therefore contains -all the properties of that element. - -.SS Scrollbar -.PP -The scrollbar uses the \fB\fChandle\fR state when drawing the small scrollbar handle. -This allows the colors used for drawing the handle to be set independently. - -.SH Widget properties -.PP -The following properties are currently supported: - -.SS all widgets -.RS -.IP \(bu 2 -\fBenabled\fP: enable/disable rendering of the widget -.IP \(bu 2 -\fBpadding\fP: padding -Padding on the inside of the widget -.IP \(bu 2 -\fBmargin\fP: padding -Margin on the outside of the widget -.IP \(bu 2 -\fBborder\fP: border -Border around the widget (between padding and margin)/ -.IP \(bu 2 -\fBborder-radius\fP: padding -Sets a radius on the corners of the borders. -.IP \(bu 2 -\fBbackground-color\fP: color -Background color -.IP \(bu 2 -\fBbackground-image\fP: image -Background image -.IP \(bu 2 -\fBborder-color\fP: color -Color of the border -.IP \(bu 2 -\fBcursor\fP: cursor -Type of mouse cursor that is set when the mouse pointer is hovered over the -widget. - -.RE - -.SS window -.RS -.IP \(bu 2 -\fBfont\fP: string -The font used in the window -.IP \(bu 2 -\fBtransparency\fP: string -Indicating if transparency should be used and what type: -.RS -.IP \(bu 2 -\fBreal\fP - True transparency. Only works with a compositor. -.IP \(bu 2 -\fBbackground\fP - Take a screenshot of the background image and use that. -.IP \(bu 2 -\fBscreenshot\fP - Take a screenshot of the screen and use that. -.IP \(bu 2 -\fBPath\fP to png file - Use an image. - -.RE - -.IP \(bu 2 -\fBlocation\fP: position - The place of the anchor on the monitor -.IP \(bu 2 -\fBanchor\fP: anchor - The anchor position on the window -.IP \(bu 2 -\fBfullscreen\fP: boolean Window is fullscreen. -.IP \(bu 2 -\fBwidth\fP: distance The width of the window -.IP \(bu 2 -\fBx-offset\fP: distance -.IP \(bu 2 -\fBy-offset\fP: distance The offset of the window to the anchor point, -allowing you to push the window left/right/up/down - -.RE - -.SS scrollbar Properties -.RS -.IP \(bu 2 -\fBbackground-color\fP: color -.IP \(bu 2 -\fBhandle-width\fP: distance -.IP \(bu 2 -\fBhandle-color\fP: color -.IP \(bu 2 -\fBborder-color\fP: color - -.RE - -.SS box -.RS -.IP \(bu 2 -\fBorientation\fP: orientation Set the direction the elements are packed. -.IP \(bu 2 -\fBspacing\fP: distance Distance between the packed elements. - -.RE - -.SS textbox -.RS -.IP \(bu 2 -\fBbackground-color\fP: color -.IP \(bu 2 -\fBborder-color\fP: the color used for the border around the widget. -.IP \(bu 2 -\fBfont\fP: the font used by this textbox (string). -.IP \(bu 2 -\fBstr\fP/\fBcontent\fP: the string to display by this textbox (string). -.IP \(bu 2 -\fBvertical-align\fP: Vertical alignment of the text. A number between 0 -(top) and 1 (bottom). -.IP \(bu 2 -\fBhorizontal-align\fP: Horizontal alignment of the text. A number between 0 -(left) and 1 (right). -.IP \(bu 2 -\fBtext-color\fP: the text color to use. -.IP \(bu 2 -\fBtext-transform\fP: text style {color} for the whole text. -.IP \(bu 2 -\fBhighlight\fP: text style {color}. color is optional, multiple -highlight styles can be added like: bold underline italic #000000; This -option is only available on the \fB\fCelement-text\fR widget. -.IP \(bu 2 -\fBwidth\fP: override the desired width for the textbox. -.IP \(bu 2 -\fBcontent\fP: Set the displayed text (String). -.IP \(bu 2 -\fBplaceholder\fP: Set the displayed text (String) when nothing is -entered. -.IP \(bu 2 -\fBplaceholder-markup\fP: If true, placeholder text supports pango -markup for stylizing. -.IP \(bu 2 -\fBplaceholder-color\fP: Color of the placeholder text. -.IP \(bu 2 -\fBblink\fP: Enable/Disable blinking on an input textbox -(Boolean). -.IP \(bu 2 -\fBmarkup\fP: Force markup on, beware that only valid pango markup -strings are shown. -.IP \(bu 2 -\fBtab-stops\fP: array of distances. Set the location of tab stops by -their distance from the beginning of the line. Each distance should be -greater than the previous one. The text appears to the right of the tab -stop position (other alignments are not supported yet). -.IP \(bu 2 -\fBcursor-width\fP: The width of the cursor. -.IP \(bu 2 -\fBcursor-color\fP: The color used to draw the cursor. -.IP \(bu 2 -\fBcursor-outline\fP: Enable a border (outline) around the cursor. -(Boolean) -.IP \(bu 2 -\fBcursor-outline-width\fP: The width of the border around the cursor. -(Double) -.IP \(bu 2 -\fBcursor-outline-color\fP: The color to use for the cursor outline. -(Color) -.IP \(bu 2 -\fBtext-outline\fP: Enable a border (outline) around the text. (Boolean) -.IP \(bu 2 -\fBtext-outline-width\fP: The width of the border around the text. (Double) -.IP \(bu 2 -\fBtext-outline-color\fP: The color to use for the text outline. (Color) - -.RE - -.SS listview -.RS -.IP \(bu 2 -\fBcolumns\fP: integer Number of columns to show (at least 1) -.IP \(bu 2 -\fBfixed-height\fP: boolean Always show \fB\fClines\fR rows, even if fewer -elements are available. -.IP \(bu 2 -\fBdynamic\fP: boolean \fB\fCTrue\fR if the size should change when filtering -the list, \fB\fCFalse\fR if it should keep the original height. -.IP \(bu 2 -\fBscrollbar\fP: boolean If the scrollbar should be enabled/disabled. -.IP \(bu 2 -\fBscrollbar-width\fP: distance Width of the scrollbar -.IP \(bu 2 -\fBcycle\fP: boolean When navigating, it should wrap around -.IP \(bu 2 -\fBspacing\fP: distance Spacing between the elements (both vertical -and horizontal) -.IP \(bu 2 -\fBlines\fP: integer Number of rows to show in the list view. -.IP \(bu 2 -\fBlayout\fP: orientation Indicate how elements are stacked. -Horizontal implements the dmenu style. -.IP \(bu 2 -\fBreverse\fP: boolean Reverse the ordering (top down to bottom up). -.IP \(bu 2 -\fBflow\fP: orientation The order the elements are layed out. -Vertical is the original 'column' view. -.IP \(bu 2 -\fBfixed-columns\fP: boolean Do not reduce the number of columns shown when -number of visible elements is not enough to fill them all. -.IP \(bu 2 -\fBrequire-input\fP: boolean Listview requires user input to be unhidden. -The list is still present and hitting accept will activate the first entry. - -.RE - -.SH Listview widget -.PP -The listview widget is special container widget. -It has the following fixed children widgets: - -.RS -.IP \(bu 2 -0 or more \fB\fCelement\fR widgets of the type box. -.IP \(bu 2 -An optional \fB\fCscrollbar\fR widget. This can be enabled using the scrollbar -property. - -.RE - -.PP -These cannot be changed using the \fB\fCchildren\fR property. - -.PP -Each Entry displayed by listview is captured by a \fB\fCbox\fR called \fB\fCelement\fR\&. -An \fB\fCelement\fR widget can contain the following special child widgets: - -.RS -.IP \(bu 2 -\fB\fCelement-icon\fR: An icon widget showing the icon associated to the entry. -.IP \(bu 2 -\fB\fCelement-text\fR: A textbox widget showing the text associated to the entry. -.IP \(bu 2 -\fB\fCelement-index\fR: A textbox widget that shows the shortcut keybinding number. - -.RE - -.PP -By default the \fB\fCelement-icon\fR and \fB\fCelement-text\fR child widgets are added to the -\fB\fCelement\fR\&. This can be modified using the \fB\fCchildren\fR property or the -\fB\fC[no]-show-icons\fR option. - -.PP -A child added with another name is treated the same as the special widget -described in the advanced layout -\[la]#advanced-layout\[ra] section. - -.SS listview text highlight -.PP -The \fB\fCelement-text\fR widget in the \fB\fClistview\fR is the one used to show the text. -On this widget set the \fB\fChighlight\fR property (only place this property is used) -to change the style of highlighting. The \fB\fChighlight\fR property consist of the -\fB\fCtext-style\fR property and a color. - -.PP -To disable highlighting: - -.PP -.RS - -.nf - element-text { - highlight: None; - } - -.fi -.RE - -.PP -To set to red underlined: - -.PP -.RS - -.nf - element-text { - highlight: underline red; - } - -.fi -.RE - -.SH Layout -.PP -The new format allows the layout of the \fBrofi\fP window to be tweaked -extensively. For each widget, the themer can specify padding, margin, border, -font, and more. It even allows, as an advanced feature, to pack widgets in a -custom structure. - -.SS Basic layout structure -.PP -The whole view is made out of boxes that pack other boxes or widgets. -The box can be vertical or horizontal. This is loosely inspired by GTK -\[la]http://gtk.org/\[ra]\&. - -.PP -The current layout of \fBrofi\fP is structured as follows: - -.PP -.RS - -.nf -┌────────────────────────────────────────────────────────────────────────────────────┐ -│ window {BOX:vertical} │ -│ ┌───────────────────────────────────────────────────────────────────────────────┐ │ -│ │ mainbox {BOX:vertical} │ │ -│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ inputbar {BOX:horizontal} │ │ │ -│ │ │ ┌─────────┐ ┌─┐ ┌───────────────────────────────┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ │ -│ │ │ │ prompt │ │:│ │ entry │ │#fr│ │ / │ │#ns│ │ci │ │ │ │ -│ │ │ └─────────┘ └─┘ └───────────────────────────────┘ └───┘ └───┘ └───┘ └───┘ │ │ │ -│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ message │ │ │ -│ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ -│ │ │ │ textbox │ │ │ │ -│ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ -│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ listview │ │ │ -│ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ -│ │ │ │ element │ │ │ │ -│ │ │ │ ┌─────────────────┐ ┌─────────────────────────────────────────────┐ │ │ │ │ -│ │ │ │ │element─icon │ │element─text │ │ │ │ │ -│ │ │ │ └─────────────────┘ └─────────────────────────────────────────────┘ │ │ │ │ -│ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ -│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌───────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ mode─switcher {BOX:horizontal} │ │ │ -│ │ │ ┌───────────────┐ ┌───────────────┐ ┌──────────────┐ ┌───────────────┐ │ │ │ -│ │ │ │ Button │ │ Button │ │ Button │ │ Button │ │ │ │ -│ │ │ └───────────────┘ └───────────────┘ └──────────────┘ └───────────────┘ │ │ │ -│ │ └───────────────────────────────────────────────────────────────────────────┘ │ │ -│ └───────────────────────────────────────────────────────────────────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────┘ - - - -.fi -.RE - -.PP -.RS - -.RS -.IP \(bu 2 -ci is the case-indicator -.IP \(bu 2 -fr is the num-filtered-rows -.IP \(bu 2 -ns is the num-rows - -.RE - -.RE - -.SS Error message structure -.PP -.RS - -.nf -┌──────────────────────────────────────────────────────────────────────────────────┐ -│ window {BOX:vertical} │ -│ ┌─────────────────────────────────────────────────────────────────────────────┐ │ -│ │ error─message {BOX:vertical} │ │ -│ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ textbox │ │ │ -│ │ └────────────────────────────────────────────────────────────────────────┘ │ │ -│ └─────────────────────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────────────────────┘ - - -.fi -.RE - -.SS Advanced layout -.PP -The layout of \fBrofi\fP can be tweaked by packing the 'fixed' widgets in a -custom structure. - -.PP -The following widgets are fixed, as they provide core \fBrofi\fP functionality: - -.RS -.IP \(bu 2 -prompt -.IP \(bu 2 -entry -.IP \(bu 2 -overlay -.IP \(bu 2 -case-indicator -.IP \(bu 2 -message -.IP \(bu 2 -listview -.IP \(bu 2 -mode-switcher -.IP \(bu 2 -num-rows -.IP \(bu 2 -num-filtered-rows - -.RE - -.PP -The following keywords are defined and can be used to automatically pack a -subset of the widgets. These are used in the default theme as depicted in the -figure above. - -.RS -.IP \(bu 2 -mainbox Packs: \fB\fCinputbar, message, listview, mode-switcher\fR -.IP \(bu 2 -inputbar Packs: \fB\fCprompt,entry,case-indicator\fR - -.RE - -.PP -Any widget name starting with \fB\fCtextbox\fR is a textbox widget, others are box -widgets and can pack other widgets. - -.PP -There are several special widgets that can be used by prefixing the name of the -widget: - -.SS Textbox widget -.PP -This is a read-only textbox widget. The displayed string can be set with \fB\fCcontent\fR\&. - -.PP -Example: - -.PP -.RS - -.nf -textbox-custom { - expand: false; - content: "My Message"; -} - -.fi -.RE - -.SS Icon -.PP -This is an icon widget. The displayed icon can be set with \fB\fCfilename\fR and size -with \fB\fCsize\fR\&. If the property \fB\fCaction\fR is set, it acts as a button. \fB\fCaction\fR can -be set to a keybinding name and completes that action. (see rofi -show keys for -a list). - -.PP -If the \fB\fCsquared\fR property is set to \fBfalse\fP the widget height and width are -not forced to be equal. - -.PP -Example: - -.PP -.RS - -.nf -icon-paste { - expand: false; - filename: "gtk-paste"; - size: 24; - vertical-align: 0.5; - action: "kb-primary-paste"; -} - -.fi -.RE - -.SS button -.PP -This is a textbox widget that can have a 'clickable' action. The \fB\fCaction\fR can -be set to: \fB\fCkeybinding\fR: accepts a keybinding name and completes that action. -(see rofi -show keys for a list). - -.PP -.RS - -.nf -button-paste { - expand: false; - content: "My Clickable Message"; - vertical-align: 0.5; - action: "kb-primary-paste"; -} - -.fi -.RE - -.SS Children -.PP -To specify children, set the \fB\fCchildren\fR -property (this always happens on the \fB\fCbox\fR child, see example below): - -.PP -.RS - -.nf -inputbar { - children: [prompt,entry,overlay,case-indicator]; -} - -.fi -.RE - -.PP -The theme needs to be updated to match the hierarchy specified. - -.PP -Below is an example of a theme emulating dmenu: - -.PP -.RS - -.nf -* { - background-color: Black; - text-color: White; - border-color: White; - font: "Times New Roman 12"; -} - -window { - anchor: north; - location: north; - width: 100%; - padding: 4px; - children: [ horibox ]; -} - -horibox { - orientation: horizontal; - children: [ prompt, entry, listview ]; -} - -listview { - layout: horizontal; - spacing: 5px; - lines: 10; -} - -entry { - expand: false; - width: 10em; -} - -element { - padding: 0px 2px; -} -element selected { - background-color: SteelBlue; -} - -.fi -.RE - -.SS Padding and margin -.PP -Just like CSS, \fBrofi\fP uses the box model for each widget. - -.PP -.RS - -.nf -┌──────────────────────────────────────────────────────────────────┐ -│ margin │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ border │ │ -│ │ ┌────────────────────────────────────────────────────────┐ │ │ -│ │ │ padding │ │ │ -│ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ -│ │ │ │ content │ │ │ │ -│ │ │ └────────────────────────────────────────────────────┘ │ │ │ -│ │ └────────────────────────────────────────────────────────┘ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────┘ - -.fi -.RE - -.PP -Explanation of the different parts: - -.RS -.IP \(bu 2 -Content - The content of the widget. -.IP \(bu 2 -Padding - Clears an area around the widget. The padding shows the -background color of the widget. -.IP \(bu 2 -Border - A border that goes around the padding and content. The border use -the border-color of the widget. -.IP \(bu 2 -Margin - Clears an area outside the border. The margin is transparent. - -.RE - -.PP -The box model allows us to add a border around elements, and to define space -between elements. - -.PP -The size of each margin, border, and padding can be set. -For the border, a linestyle and radius can be set. - -.SS Spacing -.PP -Widgets that can pack more then one child widget (currently box and listview) -have the \fB\fCspacing\fR property. This property sets the distance between the packed -widgets (both horizontally and vertically). - -.PP -.RS - -.nf -┌───────────────────────────────────────┐ -│ ┌────────┐ s ┌────────┐ s ┌────────┐ │ -│ │ child │ p │ child │ p │ child │ │ -│ │ │ a │ │ a │ │ │ -│ │ │ c │ │ c │ │ │ -│ │ │ i │ │ i │ │ │ -│ │ │ n │ │ n │ │ │ -│ └────────┘ g └────────┘ g └────────┘ │ -└───────────────────────────────────────┘ - -.fi -.RE - -.SS Advanced box packing -.PP -More dynamic spacing can be achieved by adding dummy widgets, for example to -make one widget centered: - -.PP -.RS - -.nf -┌────────────────────────────────────────────────────┐ -│ ┌───────────────┐ ┌────────┐ ┌───────────────┐ │ -│ │ dummy │ │ child │ │ dummy │ │ -│ │ expand: true; │ │ │ │ expand: true; │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ │ -│ └───────────────┘ └────────┘ └───────────────┘ │ -└────────────────────────────────────────────────────┘ - -.fi -.RE - -.PP -If both dummy widgets are set to expand, \fB\fCchild\fR will be centered. Depending on -the \fB\fCexpand\fR flag of child the remaining space will be equally divided between -both dummy and child widget (expand enabled), or both dummy widgets (expand -disabled). - -.SH Debugging -.PP -To get debug information from the parser, run rofi like: - -.PP -.RS - -.nf -G_MESSAGES_DEBUG=Parser rofi -show run - -.fi -.RE - -.PP -Syntax errors are shown in a popup and printed out to command line with the -above command. - -.PP -To see the elements queried during running, run: - -.PP -.RS - -.nf -G_MESSAGES_DEBUG=Theme rofi -show run - -.fi -.RE - -.PP -To test minor changes, part of the theme can be passed on the command line, for -example to set it to full-screen: - -.PP -.RS - -.nf -rofi -theme-str 'window { fullscreen:true;}' -show run - -.fi -.RE - -.PP -Another syntax to modify theme properties is: - -.PP -.RS - -.nf -rofi -theme+window+fullscreen true -show run - -.fi -.RE - -.PP -To print the current theme, run: - -.PP -.RS - -.nf -rofi -dump-theme - -.fi -.RE - -.SH Media support -.PP -Parts of the theme can be conditionally loaded, like the CSS \fB\fC@media\fR option. - -.PP -.RS - -.nf -@media ( min-width: 120 ) { - -} - -.fi -.RE - -.PP -It supports the following keys as constraint: - -.RS -.IP \(bu 2 -\fB\fCmin-width\fR: load when width is bigger or equal then value. -.IP \(bu 2 -\fB\fCmax-width\fR: load when width is smaller then value. -.IP \(bu 2 -\fB\fCmin-height\fR: load when height is bigger or equal then value. -.IP \(bu 2 -\fB\fCmax-height\fR: load when height is smaller then value. -.IP \(bu 2 -\fB\fCmin-aspect-ratio\fR load when aspect ratio is over value. -.IP \(bu 2 -\fB\fCmax-aspect-ratio\fR: load when aspect ratio is under value. -.IP \(bu 2 -\fB\fCmonitor-id\fR: The monitor id, see rofi -help for id's. -.IP \(bu 2 -\fB\fCenabled\fR: Boolean option to enable. Supports environment variable -or DMENU to detect if in dmenu mode. - -.RE - -.PP -@media takes an integer number or a fraction, for integer number \fB\fCpx\fR can be -added. - -.PP -.RS - -.nf -@media ( min-width: 120 px ) { - -} - -.fi -.RE - -.PP -.RS - -.nf -@media ( enabled: env(DO_LIGHT, false )) { - -} - -.fi -.RE - -.PP -.RS - -.nf -@media ( enabled: DMENU) { - -} - -.fi -.RE - -.SH Conflicting constraints -.PP -It is possible to define conflicting constraints in the theme. These conflicts -are not explicitly reported. The most common example is forcing a specific -window size, for example by enabling full-screen mode, having number of lines -set in the listview and having the listview expand to available space. There is -clearly a conflict in these 3 constraints. In this case, listview will not -limit to the number of lines, but tries to fill the available space. It is up -to the theme designer to make sure the theme handles this correctly. - -.SH Font Parsing -.PP -Rofi uses pango -\[la]https://pango.gnome.org/\[ra] for font rendering. The font should -be specified in a format that pango understands. This normally is the font name -followed by the font size. For example: - -.PP -.RS - -.nf -mono 18 - -.fi -.RE - -.PP -Or - -.PP -.RS - -.nf -FontAwesome 22 - -.fi -.RE - -.PP -From the pango manpage: - -.PP -The string must have the form - -.PP -\fB\fC\\[FAMILY-LIST] \\[STYLE-OPTIONS] \\[SIZE] \\[VARIATIONS]\fR, - -.PP -where FAMILY-LIST is a comma-separated list of families optionally terminated -by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each -word describes one of style, variant, weight, stretch, or gravity, and SIZE is -a decimal number (size in points) or optionally followed by the unit modifier -“px” for absolute size. VARIATIONS is a comma-separated list of font variation -specifications of the form “\fB\fCaxis\fR=value” (the = sign is optional). - -.PP -The following words are understood as styles: "Normal”, “Roman”, “Oblique”, -“Italic”. - -.PP -The following words are understood as variants: “Small-Caps”, “All-Small-Caps”, -“Petite-Caps”, “All-Petite-Caps”, “Unicase”, “Title-Caps”. - -.PP -The following words are understood as weights: “Thin”, “Ultra-Light”, -“Extra-Light”, “Light”, “Semi-Light”, “Demi-Light”, “Book”, “Regular”, -“Medium”, “Semi-Bold”, “Demi-Bold”, “Bold”, “Ultra-Bold”, “Extra-Bold”, -“Heavy”, “Black”, “Ultra-Black”, “Extra-Black”. - -.PP -The following words are understood as stretch values: “Ultra-Condensed”, -“Extra-Condensed”, “Condensed”, “Semi-Condensed”, “Semi-Expanded”, “Expanded”, -“Extra-Expanded”, “Ultra-Expanded”. - -.PP -The following words are understood as gravity values: “Not-Rotated”, “South”, -“Upside-Down”, “North”, “Rotated-Left”, “East”, “Rotated-Right”, “West”. - -.PP -Any one of the options may be absent. If FAMILY-LIST is absent, then the -family_name field of the resulting font description will be initialized to -NULL. If STYLE-OPTIONS is missing, then all style options will be set to the -default values. If SIZE is missing, the size in the resulting font description -will be set to 0. - -.PP -A typical example: - -.PP -"Cantarell Italic Light 15 `wght`=200" - -.SH Icon Handling -.PP -Rofi supports 3 ways of specifying an icon: - -.RS -.IP \(bu 2 -Filename -.IP \(bu 2 -icon-name, this is looked up via the icon-theme. -.IP \(bu 2 -Markup String. It renders a string as an icon. - -.RE - -.PP -For the first two options, GdkPixbuf is used to open and render the icons. -This in general gives support for most required image formats. -For the string option it uses Pango to render the string. The string needs to -start with a \fB\fC⏻" | ./rofi -dmenu - -.fi -.RE - -.PP -Getting supported icon formats: - -.PP -.RS - -.nf -G_MESSAGES_DEBUG=Helpers.IconFetcher rofi - -.fi -.RE - -.PP -This uses the debug framework and prints out a list of supported image file -extensions. - -.SH Multiple file handling -.PP -The rasi file format offers two methods of including other files. This can be -used to modify existing themes, or have multiple variations on a theme. - -.RS -.IP \(bu 2 -import: Import and parse a second file. -.IP \(bu 2 -theme: Discard theme, and load file as a fresh theme. - -.RE - -.PP -Syntax: - -.PP -.RS - -.nf -@import "myfile" -@theme "mytheme" - -.fi -.RE - -.PP -The specified file can either by \fIname\fP, \fIfilename\fP,\fIfull path\fP\&. - -.PP -If a filename is provided, it will try to resolve it in the following order: - -.RS -.IP \(bu 2 -If path is absolute and file exists, it will open the file. This includes expansion of '~' or '~user' -.IP \(bu 2 -On an \fB\fC@import\fR or \fB\fC@theme\fR it looks in the directory of the file that tried to include it. -.IP \(bu 2 -\fB\fC${XDG_CONFIG_HOME}/rofi/themes/\fR -.IP \(bu 2 -\fB\fC${XDG_CONFIG_HOME}/rofi/\fR -.IP \(bu 2 -\fB\fC${XDG_DATA_HOME}/rofi/themes/\fR -.IP \(bu 2 -\fB\fC${INSTALL PREFIX}/share/rofi/themes/\fR - -.RE - -.PP -A name is resolved (if it has no valid extension) as a filename by appending the \fB\fC\&.rasi\fR extension. - -.SH Examples -.PP -Several examples are installed together with \fBrofi\fP\&. These can be found in -\fB\fC{datadir}/rofi/themes/\fR, where \fB\fC{datadir}\fR is the install path of \fBrofi\fP -data. When installed using a package manager, this is usually: \fB\fC/usr/share/\fR\&. - -.SH SEE ALSO -.PP -rofi(1), rofi-script(5), rofi-theme-selector(1) diff --git a/doc/rofi-theme.5.markdown b/doc/rofi-theme.5.markdown index f1778e65..90a273f1 100644 --- a/doc/rofi-theme.5.markdown +++ b/doc/rofi-theme.5.markdown @@ -1,4 +1,4 @@ -# ROFI-THEME 5 rofi-theme +# rofi-theme(5) ## NAME @@ -896,15 +896,19 @@ These are appended after the name or class of the widget. #### Example -`button selected.normal { }` +``` +button selected.normal { } -`element selected.urgent { }` +element selected.urgent { } +``` Currently only the entrybox and scrollbar have states: #### Entrybox -`{visible modifier}.{state}` +``` +{visible modifier}.{state} +``` Where `visible modifier` can be: - normal: no modification @@ -1551,7 +1555,9 @@ From the pango manpage: The string must have the form -`\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]`, +```text +\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS] +``` where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE\_OPTIONS is a whitespace-separated list of words where each diff --git a/doc/rofi.1 b/doc/rofi.1 deleted file mode 100644 index 6d4c10e9..00000000 --- a/doc/rofi.1 +++ /dev/null @@ -1,1761 +0,0 @@ -.nh -.TH ROFI 1 rofi -.SH NAME -.PP -\fBrofi\fP - A window switcher, application launcher, ssh dialog, dmenu -replacement and more - -.SH SYNOPSIS -.PP -\fBrofi\fP [ -show \fImode\fP ]|[ -dmenu ]|[ -e \fImsg\fP ] [ CONFIGURATION ] - -.SH DESCRIPTION -.PP -\fBrofi\fP is an X11 pop-up window switcher, run dialog, dmenu replacement, and -more. It focuses on being fast to use and have minimal distraction. It supports -keyboard and mouse navigation, type to filter, tokenized search and more. - -.SH USAGE -.PP -\fBrofi\fP\&'s main functionality is to assist in your workflow, allowing you to -quickly switch between windows, start applications or log into a remote machine -via \fB\fCssh\fR\&. There are different \fImodes\fP for different types of actions. \fBrofi\fP -is a standalone application and should not be integrated into scripts. For -integration into scripts it has a special mode that functions as a (drop-in) -replacement for \fBdmenu(1)\fP\&. See emulating dmenu below. - -.SS Running rofi -.PP -To launch \fBrofi\fP directly in a certain mode, specify a mode with \fB\fCrofi -show -\fR\&. To show the \fB\fCdrun\fR dialog: - -.PP -.RS - -.nf - rofi -show drun - -.fi -.RE - -.PP -A useful setup in minimalistic window managers is to combine \fB\fCdrun\fR, \fB\fCrun\fR -with \fB\fCwindow\fR mode: - -.PP -.RS - -.nf - rofi -show combi -modes combi -combi-modes "window,drun,run" - -.fi -.RE - -.PP -In this setup it first list all open applications, then all installed -applications. So if you type firefox and hit return, it will switch to the -running firefox, or launch it when it is not running. - -.SS Emulating dmenu -.PP -\fBrofi\fP can emulate \fBdmenu(1)\fP (a dynamic menu for X11) when launched with -the \fB\fC-dmenu\fR flag. - -.PP -For more information see \fBrofi-dmenu(5)\fP\&. - -.SS Display Error message -.PP -\fBrofi\fP error dialog can also be called from the command line. - -.PP -.RS - -.nf - rofi -e "my message" - -.fi -.RE - -.PP -Markup support can be enabled, see CONFIGURATION options. - -.SH CONFIGURATION -.PP -There are currently three methods of setting configuration options (evaluated -in order below): - -.RS -.IP \(bu 2 -System configuration file (for example \fB\fC/etc/rofi.rasi\fR). It first checks -\fB\fCXDG_CONFIG_DIRS\fR, and then \fB\fCSYSCONFDIR\fR (that is passed at compile time). -It loads the first config file it finds, it does not merge multiple system -configuration files. -.IP \(bu 2 -Rasi theme file: The new \fItheme\fP format can be used to set configuration -values. -.IP \(bu 2 -Command-line options: Arguments passed to \fBrofi\fP\&. - -.RE - -.PP -To get a template config file, run: \fB\fCrofi -dump-config > config.rasi\fR - -.PP -This will contain (commented) all current configuration options, modified -options are uncommented. - -.PP -To get a template config file that sets the icon-theme run: \fB\fCrofi -icon-theme -hicolor -dump-config\fR\&. - -.PP -It is \fBstrongly\fP recommended to use this as a starting point for your -configuration. - -.PP -An empty configuration section in the config file looks like: - -.PP -.RS - -.nf -configuration { - // set config options here -} - -.fi -.RE - -.PP -Most of the configuration options mentioned below (beside options like \fB\fC-show\fR, -\fB\fC-dump-config\fR that apply to a single run) can be set here. - -.PP -For example to set the dpi value to 72: - -.PP -.RS - -.nf -configuration { - dpi: 72; -} - -.fi -.RE - -.PP -The configuration system supports the following types: - -.RS -.IP \(bu 2 -string -.IP \(bu 2 -integer (signed and unsigned) -.IP \(bu 2 -char -.IP \(bu 2 -boolean -.IP \(bu 2 -lists - -.RE - -.PP -For the syntax of these options, see the \fBrofi-theme(5)\fP manpage. - -.PP -For use on the command line, Boolean options have a non-default command-line -syntax. Example to enable option X: - -.PP -.RS - -.nf - -X - -.fi -.RE - -.PP -To disable option X: - -.PP -.RS - -.nf - -no-X - -.fi -.RE - -.PP -Below is a list of the most important options: - -.SS General -.PP -\fB\fC-help\fR - -.PP -The help option shows the full list of command-line options and the current set -values. These include dynamic (run-time generated) options. - -.PP -\fB\fC-version\fR - -.PP -Show the \fBrofi\fP version and exit. - -.PP -\fB\fC-dump-config\fR - -.PP -Dump the current active configuration, in rasi format, to stdout and exit. -Information about the rasi format can be found in the \fBrofi-theme(5)\fP manpage. - -.PP -\fB\fC-dump-theme\fR - -.PP -Dump the current active theme, in rasi format, to stdout and exit. - -.PP -\fB\fC-rasi-validate\fR \fIfilename\fP - -.PP -Try to parse the file and return 0 when successful, non-zero when failed. - -.PP -\fB\fC-list-keybindings\fR - -.PP -List all known keybindings without trying to parse them. This can be used to -look for duplicate bindings. - -.PP -\fB\fC-threads\fR \fInum\fP - -.PP -Specify the number of threads \fBrofi\fP should use: - -.RS -.IP \(bu 2 -0: Autodetect the number of supported hardware threads. -.IP \(bu 2 -1: Disable threading -.IP \(bu 2 -2..n: Specify the maximum number of threads to use in the thread pool. - -.RE - -.PP -Default: Autodetect - -.PP -\fB\fC-display\fR \fIdisplay\fP - -.PP -The X server to contact. Default is \fB\fC$DISPLAY\fR\&. - -.PP -\fB\fC-dmenu\fR - -.PP -Run \fBrofi\fP in dmenu mode. This allows for interactive scripts. -In \fB\fCdmenu\fR mode, \fBrofi\fP reads from STDIN, and output to STDOUT. -A simple example, displaying three pre-defined options: - -.PP -.RS - -.nf - echo -e "Option #1\\nOption #2\\nOption #3" | rofi -dmenu - -.fi -.RE - -.PP -Or get the options from a script: - -.PP -.RS - -.nf - ~/my_script.sh | rofi -dmenu - -.fi -.RE - -.PP -See the \fBrofi-dmenu(5)\fP manpage for more information. - -.PP -\fB\fC-show\fR \fImode\fP - -.PP -Open \fBrofi\fP in a certain mode. Available modes are \fB\fCwindow\fR, \fB\fCrun\fR, \fB\fCdrun\fR, -\fB\fCssh\fR, \fB\fCcombi\fR\&. The special argument \fB\fCkeys\fR can be used to open a searchable -list of supported key bindings -(see the \fBrofi-keys(5)\fP manpage) - -.PP -To show the run-dialog: - -.PP -.RS - -.nf - rofi -show run - -.fi -.RE - -.PP -If \fB\fC-show\fR is the last option passed to rofi, the first enabled modes is shown. - -.PP -\fB\fC-modes\fR \fImode1,mode2\fP - -.PP -Specify an ordered, comma-separated list of modes to enable. -Enabled modes can be changed at runtime. Default key is \fB\fCCtrl+Tab\fR\&. -If no modes are specified, all configured modes will be enabled. -To only show the \fB\fCrun\fR and \fB\fCssh\fR launcher: - -.PP -.RS - -.nf - rofi -modes "run,ssh" -show run - -.fi -.RE - -.PP -Custom modes can be added using the internal \fB\fCscript\fR mode. Each such mode has -two parameters: - -.PP -.RS - -.nf -: