wofi(7)

🎀 WOFI 🎀

okay bestie, welcome to wofi(7) from the Miscellaneous Information Manual — this is the page about all the built-in modes and the extra little features, and yes we are gonna get through literally all of it together 💅

---

✨ NAME ✨

wofi — built in modes and other features. that's it, that's the name, slay.

---

🌸 DESCRIPTION 🌸

So wofi has a bunch of built in modes plus a whole lot of other features — including combi — and this page is where all of that gets documented. you're in the right place, babe 🫶

important thing first: every config option written up here is stripped of its mode name. Mode specific options get put in the config file in the format mode-example_opt=val.

Example so it's crystal clear: dmenu has an option called parse_action, so in the config file you'd write it like this:

dmenu-parse_action=true

see? mode name, dash, option. that's the whole vibe ✨

---

👑 MODES 👑

right now wofi has 3 built in modes:

1. run — searches $PATH for executables and lets you run them by selecting them.
2. drun — searches $XDG_DATA_HOME/applications and $XDG_DATA_DIRS/applications for desktop files and lets you run them by selecting them.
3. dmenu — reads from stdin, shows you the options, and whatever you select gets output to stdout.

if $XDG_DATA_HOME isn't specified it defaults to ~/.local/share. if $XDG_DATA_DIRS isn't specified it defaults to:

/usr/local/share:/usr/share

Now — combi. it's not a mode, bestie, it's a feature. you use it like this:

--show mode1,mode2,mode3,etc

you can mix and match any number of modes, BUT each mode can only be loaded once. so something like --show run,drun,run is not supported. (and honestly? not sure why you'd do that in the first place 😭)

---

💅 DMENU CONFIG OPTIONS 💅

• parse_action=BOOL — if true, the result dmenu hands back gets stripped of image escape sequences and pango markup. default is false.
• separator=CHAR — the character used to separate dmenu entries. default is \n.
• print_line_num=BOOL — when an entry gets selected, instead of printing the entry itself it prints the number of the line that entry was on. heads up: this disables caching, because it's fundamentally incompatible with it.

---

🔥 RUN 🔥

in run mode, holding ctrl while running an entry makes the arguments get parsed — even if always_parse_args=false. holding shift makes the entry run in a terminal. little keyboard shortcuts, big energy 💖

🌈 RUN CONFIG OPTIONS 🌈

• always_parse_args=BOOL — if true, spaces won't be treated as part of the executable name, they get treated as an argument separator — same thing as holding control while pressing enter. default is false.
• show_all=BOOL — if true, shows all the entries in path, including entries that have the same executable name. for example /bin/bash and /usr/bin/bash get shown separately as bash, instead of there just being one bash entry for the first one encountered. default is true.
• print_command=BOOL — if true, the executable that would be run gets printed to stdout instead of actually being executed. default is false.

---

🦋 DRUN CONFIG OPTIONS 🦋

• print_command=BOOL — if true, the command used to launch the desktop file gets printed to stdout instead of being invoked. default is false.
• display_generic=BOOL — if true, generic names get displayed in () right next to the application name. default is false.
• disable_prime=BOOL — if true, wofi will ignore the PrefersNonDefaultGPU desktop variable — specifically, this stops wofi from setting DRI_PRIME. default is false.
• print_desktop_file=BOOL — if true, the path to the desktop file and the name of the corresponding action (if there is one) get printed to stdout instead of being invoked. default is false.
• ignore_metadata=BOOL — if true, only the application's name gets searched, instead of the normal behavior of searching a large amount of metadata — including category and description. default is false.

---

🍓 DRUN 🍓

when images are enabled, drun mode will pull icon themes. but because it's a GTK app, there's a real chance you'll need to run gtk-update-icon-cache to get them to actually apply. just a lil heads up 🧚

---

💜 LOCATIONS 💜

there are 9 possible locations, and you can specify them either by name or by number. the numbering scheme is the same as in rofi, and the matching number is listed next to each name below. the default is center.

1. center — 0
2. top_left — 1
3. top — 2
4. top_right — 3
5. right — 4
6. bottom_right — 5
7. bottom — 6
8. bottom_left — 7
9. left — 8

okay now the ✨math✨ of offsets, stay with me. the x and y offsets are applied based on layer-shell anchors, which means an x offset can only be applied if wofi is anchored on the x axis. so basically: you can only use an x offset with the top_left, top_right, right, bottom_right, bottom_left, and left locations. center, top, and bottom can't have x offsets because they're not anchored on the x axis.

likewise, y offsets can only be applied to top_left, top, top_right, bottom_right, bottom, and bottom_left locations. center, left, and right can't have y offsets because they're not anchored to the y axis.

and since center can't have offsets on either — it's not anchored to any axis — any x or y offset applied while using center will override the location to top_left, for backwards compatibility reasons. (because otherwise the offsets would just get ignored anyway, so like, at least it does something 💀)

---

⭐ ORDER ⭐

there are 2 order options right now: default and alphabetical.

• default means entries are displayed in the order they get added by the mode. for all the built in modes this is cached items first, followed by other entries in no specific order.
• alphabetical means entries are alphabetically sorted. period.

these orders only affect the order when no search has been entered. once a search is entered, the order gets re-arranged based on the current matching preference, and this order is ignored.

---

🎀 CACHING 🎀

caching cannot be disabled. but bestie, you can set the cache file to /dev/null to effectively disable it. loophole queen 💅

---

🪟 WINDOW SWITCHER 🪟

okay so wofi does not have the ability to do window switching on its own, because there's no way to do that with wayland/wlroots protocols. sad, but true 😭

however! if you're using sway, you can use swaymsg with dmenu mode to pull it off. here's the script:

swaymsg -t get_tree |
  jq -r '.nodes[].nodes[] | if .nodes then [recurse(.nodes[])] else []
end + .floating_nodes | .[] | select(.nodes==[]) | ((.id | tostring) + "
" + .name)' |
  wofi --show dmenu | {
    read -r id name
    swaymsg "[con_id=$id]" focus
}

go off, you just got window switching on wayland 🫶

---

🌈 WIDGET LAYOUT 🌈

this section is for advanced CSS — the kind that needs more control than the built in wofi CSS names/classes allow for.

⚠️ this widget layout is subject to change at any time and without warning, so your CSS might very well break if you rely on this. be careful out there, babe.

widgets have their corresponding names next to them if they have one. here's the whole tree:

window - #window
    box - #outer-box
        entry - #input

        scrolledwindow - #scroll
            viewport
                box
                    flowbox - #inner-box
                        flowboxchild - #entry

                            .entry - #unselected or #selected
                                image
                                label

                            expander
                                .entry - #unselected or #selected
                                    image
                                    label

                                list
                                    row - #entry
                                        .entry - #unselected or #selected
                                            image
                                            label
            scrollbar

now let me walk you through what all of that actually means:

• the first .entry (#unselected or #selected) only exists if there's ONLY 1 action. it's a WofiPropertyBox which has no CSS node and should probably not be used. its name depends on whether or not the entry is selected. see wofi(5) on #selected and #unselected for info.
  • image — only present if there's an image in the entry, and it might occur multiple times if multiple images are present.
  • label — only present if there's text in the entry, and it might occur multiple times if there are multiple text objects in a single entry.
• expander — this and its children only exist if there are multiple actions on the entry.
  • .entry (#unselected or #selected) — this is the main action. it's a WofiPropertyBox which has no CSS node and should probably not be used. the name depends on whether or not the entry is selected. see wofi(5) on #selected and #unselected for info.
    • image — only present if there's an image in the entry, and it might occur multiple times if multiple images are present.
    • label — only present if there's text in the entry, and it might occur multiple times if there are multiple text objects in a single entry.
  • list — this contains all the secondary actions.
    • row - #entry
      • .entry (#unselected or #selected) — a WofiPropertyBox which has no CSS node and should probably not be used. the name depends on whether or not the entry is selected. see wofi(5) on #selected and #unselected for info.
        • image — only present if there's an image in the entry, and it might occur multiple times if multiple images are present.
        • label — only present if there's text in the entry, and it might occur multiple times if there are multiple text objects in a single entry.

---

and that's the whole page, bestie 🥹 that was wofi(7) from the Miscellaneous Information Manual — yes the footer really is just wofi(7), she's mysterious like that 💅✨ go forth and slay your configs 💖