Added API documentation

man/wofi-api.3

@@ -0,0 +1,105 @@
+.TH wofi\-api 3
+.SH NAME
+wofi \- API functions and documentation
+
+.SH DESCRIPTION
+The functions documented here are used for interacting with wofi. They are defined in wofi_api.h.
+
+.SH STRUCTURES
+struct cache_line {
+.RS 4
+char* line;
+.br
+struct wl_list link;
+.RE
+};
+
+.SH API FUNCTIONS
+The following functions are used to interact with wofi.
+
+.TP
+.B char* wofi_parse_image_escapes(const char* text)
+This function takes in text containing image escapes and pango markup and will return the plain text with all of that stripped. The string returned is newly allocated and should be freed by the caller when they are done with it.
+
+.B const char* text
+\- The input text containing image escapes and pango markup.
+
+.TP
+.B void wofi_write_cache(struct mode* mode, const char* cmd)
+Writes an entry to the cache file.
+
+.B struct mode* mode
+\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
+
+.B const char* cmd
+\- The entry to write to the cache file. If this entry already exists the number of times it has been written will be incremented.
+
+.TP
+.B void wofi_remove_cache(struct mode* mode, const char* cmd)
+Removes an entry from the cache file.
+
+.B struct mode* mode
+\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
+
+.B const char* cmd
+\- The entry to remove from the cache file. This does NOT decrement the number of times written, it fully removes the entry.
+
+.TP
+.B struct wl_list* wofi_read_cache(struct mode* mode)
+Reads the cache and returns a \fBstruct wl_list*\fR containing the entires. The list is made up of \fBstruct cache_line*\fR entries. The wayland documentation should be referred to for the usage of a wl_list.
+
+.B struct mode* mode
+\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
+
+.TP
+.B struct widget* wofi_create_widget(struct mode* mode, char* text[], char* search_text, char* actions[], size_t action_count)
+Creates a widget from the specified information. This widget should be returned by the mode's \fBget_widget()\fR function in order to be displayed.
+
+.B struct mode* mode
+\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
+
+.B char* text[]
+\- The array of text to display on the entry in wofi. Each element in the array represents the text for 1 action. The array should only be larger than 1 if you're creating a multi\-action entry. Multi\-action entries need to provide 1 string for every action the entry has.
+
+.B char* search_text
+\- The text which the user can search for to find this widget.
+
+.B char* actions[]
+\- The array of actions for the entry. An action is the text given to a mode's \fBexec()\fR function when the user selects an entry. Multi\-action entries need to provide 1 action string for every action the entry has.
+
+.B size_t action_count
+\- The number of actions the entry will have.
+
+.TP
+.B void wofi_insert_widgets(struct mode* mode)
+This will requery the mode for more widgets.
+
+.B struct mode* mode
+\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
+
+.TP
+.B bool wofi_allow_images(void)
+Returns true if the user enabled images, false otherwise.
+
+.TP
+.B bool wofi_allow_markup(void)
+Returns true if the user enabled pango markup, false otherwise.
+
+.TP
+.B uint64_t wofi_get_image_size(void)
+Returns the user specified image size, 32 by default. Wofi will scale images for you, this is just informational and is not required but can be helpful if multiple sizes are available.
+
+.TP
+.B bool wofi_mod_shift(void)
+Returns true if the user was holding shift when selecting an entry, false otherwise.
+
+.TP
+.B bool wofi_mod_control(void)
+Returns true if the user was holding control when selecting an entry, false otherwise.
+
+.TP
+.B void wofi_term_run(const char* cmd)
+Runs the provided cmd in a terminal emulator. The following order is used for picking a terminal emulator: The user specified terminal, kitty, termite, gnome\-terminal, weston\-terminal. If none of these can be found execution will fail.
+
+.B const char* cmd
+\- The command to run, this is invoked by doing \fBterm \-\- cmd\fR.

man/wofi-map.3

@@ -0,0 +1,74 @@
+.TH wofi\-map 3
+.SH NAME
+wofi \- Map API functions and documentation
+
+.SH DESCRIPTION
+The functions documented here are used for interacting with wofi's config and map. They are defined in map.h.
+
+.SH MAP FUNCTIONS
+The following functions are used to interact with a \fBstruct map*\fR
+
+.TP
+.B struct map* map_init(void)
+Allocates and returns a new string map. String maps only support string values.
+
+.TP
+.B struct map* map_init_void(void)
+Allocates and returns a new void map. A void map supports values of any type.
+
+.TP
+.B void map_free(struct map* map)
+Frees the provided map and all it's keys. Values are only freed if it is a string map.
+
+.TP
+.B bool map_put(struct map* map, const char* key, char* value)
+Returns true if the given map is a string map, otherwise returns false and prints a message to stderr.
+
+.B struct map* map
+\- The map to insert into.
+
+.B const char* key
+\- The key to store the value under. This key is given to \fBstrdup()\fR before being saved and will be freed when running \fBmap_free()\fR.
+
+.B char* value
+\- The value to store. This value is given to \fBstrdup()\fR before being saved and will be freed when running \fBmap_free()\fR. If the value is \fBNULL\fR it will not be given to \fBstrdup()\fR.
+
+.TP
+.B bool map_put_void(struct map* map, const char* key, void* value)
+Returns true if the given map is a void map, otherwise returns false and prints a message to stderr.
+
+.B struct map* map
+\- The map to insert into.
+
+.B const char* key
+\- The key to store the value under. This key is given to \fBstrdup()\fR before being saved and will be freed when running \fBmap_free()\fR.
+
+.B void* value
+\- The value to store. This pointer is stored in the map, it is on the caller to free this and it will not be freed when running \fBmap_free()\fR.
+
+.TP
+.B void* map_get(struct map* map, const char* key)
+Returns the value stored under \fBkey\fR or \fBNULL\fR if no key exists. \fBNULL\fR can also be returned if it was stored there with \fBmap_put()\fR or \fBmap_put_void()\fR.
+
+.B struct map* map
+\- The map to get the value from.
+
+.B const char* key
+\- The key to lookup.
+
+.TP
+.B bool map_contains(struct map* map, const char* key)
+Returns true if the key exists, false otherwise. This is implemented as a \fBvalue != NULL\fR check so a \fBNULL\fR value is considered to not exist.
+
+.B struct map* map
+\- The map to check against.
+
+.B const char* key
+\- The key to check for.
+
+.TP
+.B size_t map_size(struct map* map)
+Returns the number of entries in this map.
+
+.B struct map* map
+\- The map to get the size of.

man/wofi.3

@@ -0,0 +1,47 @@
+.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)
+Definining this function is required. This function is called to setup your plugin and provide it with serveral 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 const char** get_arg_names(void)
+Definining 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)
+Definining 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)
+Definining 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)
+Definining 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)
+Definining 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.