wofi/man/wofi.3

.TH wofi 3
.SH NAME
wofi \- Mode functions and documentation

.SH DESCRIPTION
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.

.SH HEADER FILES
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.

.SH MODE FUNCTIONS
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.

.TP
.B void init(struct mode* mode, struct map* config)
Defining this function is required. This function is called to setup your plugin and provide it with several pointers which are described below.

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

.B 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 \fBwofi\-map(3)\fR.

.TP
.B void load(struct mode* mode)
Defining this function is optional. This function is called before ALL others and provides your mode pointer as early as possible.

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

.TP
.B const char** get_arg_names(void)
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 \fB{"opt1", "opt2"}\fR the config options defined will be \fBmode-opt1=\fIvalue\fR and \fBmode-opt2=\fIvalue\fR where mode is the name of the shared object.

.TP
.B size_t get_arg_count(void)
Defining this function is optional. This function is called to get the number of arguments returned by \fBget_arg_names(void)\fR.

.TP
.B void exec(const char* cmd)
Defining this function is required. This function is called when the user selects an entry.

.B 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.

.TP
.B struct widget* get_widget(void)
Defining this function is optional. This function is called to request the next widget to be added. See \fBwofi_create_widget()\fR in \fBwofi\-api(3)\fR on how to obtain a \fBstruct widget*\fR. \fBNULL\fR should be returned to denote no more widgets are available.

.TP
.B bool no_entry(void)
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.