NAME

       wofi - Mode functions and documentation

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.

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.

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.

       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.

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

       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.

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

       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 {"opt1", "opt2"} the config options defined will be mode-
              opt1=value and mode-opt2=value where mode is the name of the shared object.

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

       void exec(const char* cmd)
              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.

       struct widget* get_widget(void)
              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.

       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.

                                                                                                         wofi(3)