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)