DOKK / manpages / debian 11 / wofi / wofi.3.en
wofi(3) Library Functions Manual wofi(3)

wofi - Mode functions and documentation

Wofi provides a C API which can be used for developing 3rd party modes. These modes should be compiled to a shared object which should be placed in $XDG_CONFIG_HOME/wofi/plugins. If $XDG_CONFIG_HOME is not defined then it will default to ~/.config.

It is very important to note that this API is not stable. It's mostly stable however if something comes up that requires a substantial change things will be changed. This shouldn't happen too much but has happened in the past and might in the future.

There are 2 header files required in order to use the wofi API, wofi_api.h and map.h. utils.h might be useful to include if you want a few helper functions but it is not required. utils.h will not be documented here as it's outside the scope of the mode API.

The following list of functions are the functions which can be defined inside of your mode which will be called to do setup, and acquire various pieces of information from the mode.

Defining this function is required. This function is called to setup your plugin and provide it with several pointers which are described below.

struct mode* mode - used to identify your mode, it is passed to a large number of the API functions to identify your mode.

struct map* config - all of the config options that the user defined for your mode. Information on how to access this can be found in wofi-map(3).

Defining this function is optional. This function is called before ALL others and provides your mode pointer as early as possible.

struct mode* mode - used to identify your mode, it is passed to a large number of the API functions to identify your mode.

Defining this function is optional. This function is called to get an array of config options which can be set by the user. All of these options have the name of your mode prefixed on the front so if your array is for example {"opt1", "opt2"} the config options defined will be mode-opt1=value and mode-opt2=value where mode is the name of the shared object.

Defining this function is optional. This function is called to get the number of arguments returned by get_arg_names(void).

Defining this function is required. This function is called when the user selects an entry.

const char* cmd - The action registered to the selected entry. If your mode allows executing searches directly then this will be the search contents if no matching entries exist.

Defining this function is optional. This function is called to request the next widget to be added. See wofi_create_widget() in wofi-api(3) on how to obtain a struct widget*. NULL should be returned to denote no more widgets are available.

Defining this function is optional. This function is called to find out whether or not this mode supports running searches without any matching entries. The default is false, if you wish to allow your mode to take searches directly you must define this and return true.