wofi-api(3)

💖 wofi-api(3) — the manual, but make it bestie 💖

Library Functions Manual · wofi-api(3)

✨ NAME ✨

wofi — API functions and documentation 🫶

🌸 DESCRIPTION 🌸

okay so. the functions we're documenting right here are the ones you use to talk to wofi. they live in wofi_api.h, no cap. if you're writing a mode and you wanna vibe with wofi's internals, this is your girl. 💅

🎀 STRUCTURES 🎀

the one and only:

struct cache_line {
    char* line;
    struct wl_list link;
};

she's little, she's iconic, she's the building block of your cache reads. 💜

👑 API FUNCTIONS 👑

these are the functions you use to interact with wofi. go off, bestie.

• char* wofi_parse_image_escapes(const char* text) — so you hand her some text that's full of image escapes and pango markup, and she hands you back the plain text with all of that stripped out. the string you get back is newly allocated, so the caller (that's you, babe) has to free it when you're done. don't leak her, she deserves better. 😭
  • const char* text — the input text containing image escapes and pango markup.
• void wofi_write_cache(struct mode* mode, const char* cmd) — writes an entry to the cache file. ✍️
  • struct mode* mode — the struct mode* given to your mode's init() function.
  • const char* cmd — the entry to write to the cache file. if this entry already exists, the number of times it has been written gets incremented. so it's not just "added", it's counted. 📈
• void wofi_remove_cache(struct mode* mode, const char* cmd) — removes an entry from the cache file. 🗑️
  • struct mode* mode — the struct mode* given to your mode's init() function.
  • const char* cmd — the entry to remove from the cache file.

⚠️ listen. this does NOT decrement the number of times written. it fully removes the entry. she's gone. periodt. 💀

• struct wl_list* wofi_read_cache(struct mode* mode) — reads the cache and returns a struct wl_list* containing the entries. that list is made up of struct cache_line* entries, and for how to actually use a wl_list you should go read the wayland documentation. not me outsourcing the wl_list lore but here we are. 🦋
  • struct mode* mode — the struct mode* given to your mode's init() function.
• struct widget* wofi_create_widget(struct mode* mode, char* text[], char* search_text, char* actions[], size_t action_count) — creates a widget from all the info you give her. 💖 and then — important — this widget should be returned by the mode's get_widget() function so it actually shows up on screen. no returning it = no display, that's the whole vibe check. 👑
  • struct mode* mode — the struct mode* given to your mode's init() function.
  • char* text[] — the array of text to display on the entry in wofi. each element in the array represents the text for 1 action. the array should only be larger than 1 if you're creating a multi-action entry. and multi-action entries need to provide 1 string for every action the entry has. one string per action, no skipping. 🎯
  • char* search_text — the text which the user can search for to find this widget. 🔍
  • char* actions[] — the array of actions for the entry. an action is the text given to a mode's exec() function when the user selects an entry. multi-action entries need to provide 1 action string for every action the entry has. (see? one per action again. consistency slay.) ✨
  • size_t action_count — the number of actions the entry will have.
• void wofi_insert_widgets(struct mode* mode) — this will requery the mode for more widgets. more widgets, more life. 🧚
  • struct mode* mode — the struct mode* given to your mode's init() function.
• char* wofi_get_dso_path(struct mode* mode) — returns the path to this mode's DSO if it's an external mode. returns NULL otherwise. so like… internal modes, y'all get nothing, sorry bestie. 🙈
  • struct mode* mode — the struct mode* given to your mode's init() function.
• bool wofi_allow_images(void) — returns true if the user enabled images, false otherwise. 🖼️
• bool wofi_allow_markup(void) — returns true if the user enabled pango markup, false otherwise. 🎨
• uint64_t wofi_get_image_size(void) — returns the user specified image size, 32 by default. wofi will scale images for you, so this is just informational and is not required — but it's lowkey helpful if multiple sizes are available. 🌈
• bool wofi_mod_shift(void) — returns true if the user was holding shift when selecting an entry, false otherwise. 🫶
• bool wofi_mod_control(void) — returns true if the user was holding control when selecting an entry, false otherwise. 💅
• void wofi_term_run(const char* cmd) — runs the provided cmd in a terminal emulator. 🖥️ and the order she uses for picking a terminal emulator is, in order:
  1. the user specified terminal
  2. kitty
  3. alacritty
  4. wezterm
  5. foot
  6. termite
  7. gnome-terminal
  8. weston-terminal

if none of these can be found, execution will fail. that's it, that's the list, that's the whole rollout. 😭

• const char* cmd — the command to run. this is invoked by doing term -- cmd.

• void wofi_exit(void) — this function is how you should call to exit wofi. 🚪✨ it checks the status given and only sets a custom exit code if you pass EXIT_SUCCESS.

⚠️ real talk: if you call the libc exit() function instead, then the custom exit code will always be used, even if an error should be reported. so don't do that, use this one, she knows what she's doing. 🔥

and that's the whole page, bestie!! 🌟 this was wofi-api(3) from the Library Functions Manual — go build something iconic with it, mwah 💋 🎀🦋💖