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)