assada/dotfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

init commit

Browse Source
This commit is contained in:
assada
2024-05-14 12:29:49 +03:00
commit 29ce74f3f6
209 changed files with 17530 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
wofi/man/wofi-api.3 Normal file
View File

@@ -0,0 +1,116 @@
.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 char* wofi_get_dso_path(struct mode* mode)
Returns the path to this mode's DSO if it's an external mode, returns NULL otherwise.
.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, alacritty, wezterm, foot, 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.
.TP
.B void wofi_exit(void)
This function is how you should call to exit wofi. It checks the status given and only sets a custom exit code if you pass EXIT_SUCCESS. If you call the libc exit() function then the custom exit code will always be used even if an error should be reported

61
wofi/man/wofi-config.3 Normal file
View File

@@ -0,0 +1,61 @@
.TH wofi\-config 3
.SH NAME
wofi \- Config functions and documentation
.SH DESCRIPTION
The functions documented here are used for manipulating maps that represent config entries. They are defined in config.h.
.SH CONFIG FUNCTIONS
The following functions are used to work with configs.
.TP
.B void config_put(struct map* map, char* line)
Parses a single config line and inserts the result into the map
.B struct map* map
\- The map to insert into.
.B char* line
\- The config line to insert. Should be in the format of \fBkey=\fIvalue\fR.
.TP
.B void config_load(struct map* map, const char* config)
Loads a config file into the given map
.B struct map* map
\- The map to load the config into.
.B const char* config
\- The path to a config file. Should contain lines with the format of \fBkey=\fIvalue\fR.
.TP
.B char* config_get(struct map* config, const char* key, char* def_opt)
Gets a config entry, if the entry is not set then it returns \fBdef_opt\fR.
.B struct map* config
\- The map to get the value from.
.B const char* key
\- The key to lookup.
.B char* def_opt
\- The default value to be returned if the key does not exist.
.TP
.B int config_get_mnemonic(struct map* config, const char* key, char* def_opt, int num_choices, ...)
Gets an enum value from the config. If the value is not set then it returns \fBdef_opt\fR.
.B struct map* config
\- The map to get the value from.
.B const char* key
\- The key to lookup.
.B char* def_opt
\- The default value to be returned if the key does not exist.
.B int num_choices
\- The number of enum options available.
.B varargs
\- The list of enum options available.

4552
wofi/man/wofi-keys.7 Normal file
View File

File diff suppressed because it is too large Load Diff

74
wofi/man/wofi-map.3 Normal file
View File

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

63
wofi/man/wofi-utils.3 Normal file
View File

@@ -0,0 +1,63 @@
.TH wofi\-utils 3
.SH NAME
wofi \- Utility functions and documentation
.SH DESCRIPTION
The functions documented here are general utility functions. They are defined in utils.h.
.SH UTILITY FUNCTIONS
The following functions are general convenience functions.
.TP
.B time_t utils_get_time_millis(void)
Returns the current unix time in milliseconds.
.TP
.B void utils_sleep_millis(time_t millis)
Sleeps for the specified amount of time.
.B time_t millis
\- The time to sleep for in milliseconds.
.TP
.B char* utils_concat(size_t arg_count, ...)
Concatenates strings together. The returned result is newly allocated and must be freed by the caller when finished using it.
.B size_t arg_count
\- The number of arguments provided
.B varargs
\- The list of strings to be concatenated.
.TP
.B size_t utils_min(size_t n1, size_t n2)
Returns the smaller of the two inputs.
.B size_t n1
\- The first number.
.B size_t n2
\- The second number.
.TP
.B size_t utils_min3(size_t n1, size_t n2, size_t n3)
Returns the smallest of the three inputs.
.B size_t n1
\- The first number.
.B size_t n2
\- The second number.
.B size_t n3
\- The third number.
.TP
.B size_t utils_distance(const char* haystack, const char* needle)
Computes the Levenshtein distance between the two inputs.
.B const char* haystack
\- The string to search in.
.B const char* needle
\- The string to search for.

112
wofi/man/wofi-widget-builder.3 Normal file
View File

@@ -0,0 +1,112 @@
.TH wofi\-widget\-builder 3
.SH NAME
wofi \- Widget builder API functions
.SH DESCRIPTION
The functions documented here are used for building custom widgets with more power and flexibility than previously allowed. They are defined in wofi_widget_builder_api.h
.TP
.B struct widget_builder* wofi_widget_builder_init(struct mode* mode, size_t actions)
Creates multiple widget builders. The number of builders created is specified by actions and is returned as an array.
.B struct mode* mode
\- The \fBstruct mode*\fR given to your mode's \fBinit()\fR function.
.B size_t actions
\- The number of builders to create
.TP
.B void wofi_widget_builder_set_search_text(struct widget_builder* builder, char* search_text)
Sets the search text for the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to set the search text for
.B char* search_text
\- The text to set as the search text
.TP
.B void wofi_widget_builder_set_action(struct widget_builder* builder, char* action)
Sets the action for the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to set the action for
.B char* action
\- The text to set as the action
.TP
.B void wofi_widget_builder_insert_text(struct widget_builder* builder, char* text, ...)
Inserts text into the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to add the text to
.B char* text
\- The text to add to the widget
.B ...
\- The names of the CSS classes for this text. The class that will be assigned is .mode_name-css_name where mode_name is the name of the mode, i.e. drun etc. This should have a NULL sentinel
.TP
.B void wofi_widget_builder_insert_text_with_list(struct widget_builder* builder, char* text, struct wl_list* classes)
Inserts text into the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to add the text to
.B char* text
\- The text to add to the widget
.B struct wl_list* classes
\- The names of the CSS classes for this text. The class that will be assigned is .mode_name-css_name where mode_name is the name of the mode, i.e. drun etc. This list should contain struct css_class nodes.
.TP
.B void wofi_widget_builder_insert_image(struct widget_builder* builder, GdkPixbuf* pixbuf, ...)
Inserts an image into the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to add the image to
.B GdkPixbuf* pixbuf
\- The image to add to the widget
.B ...
\- The names of the CSS classes for this image. The class that will be assigned is .mode_name-css_name where mode_name is the name of the mode, i.e. drun etc. This should have a NULL sentinel
.TP
.B void wofi_widget_builder_insert_image_with_list(struct widget_builder* builder, GdkPixbuf* pixbuf, struct wl_list* classes)
Inserts an image into the widget specified by the builder
.B struct widget_builder* builder
\- The builder that contains the widget to add the image to
.B GdkPixbuf* pixbuf
\- The image to add to the widget
.B struct wl_list* classes
\- The names of the CSS classes for this image. The class that will be assigned is .mode_name-css_name where mode_name is the name of the mode, i.e. drun etc. This list should contain struct css_class nodes.
.TP
.B struct widget_builder* wofi_widget_builder_get_idx(struct widget_builder* builder, size_t idx)
Gets the widget_builder at the provided index in the array
.B struct widget_builder* builder
\- The array of builders to get the builder from
.B size_t idx
\- The index in the array to get
.TP
.B struct widget* wofi_widget_builder_get_widget(struct widget_builder* builder)
Constructs a new widget from the specified builder, the widget can be returned by \fBstruct widget* get_widget(void)\fR
.B struct widget_builder* builder
\- The builder to construct a widget for
.TP
.B void wofi_widget_builder_free(struct widget_builder* builder)
Frees the specified builder
.B struct widget_builder* builder
\- The builder to free

135
wofi/man/wofi.1 Normal file
View File

@@ -0,0 +1,135 @@
.TH wofi 1
.SH NAME
wofi \- A rofi inspired launcher for wlroots compositors
.SH SYNOPSIS
.B wofi
[options]
.SH DESCRIPTION
.B wofi
is a rofi inspired menu program for wlroots compositors such as sway. It is intended to be highly customizable and flexible with the help of CSS styling and a dmenu mode that allows for endless scriptability. Wofi can be run cacheless in dmenu mode automatically by invoking it as dmenu with symlink.
Wofi was designed specifically for wlroots and makes use of the wlr\-layer\-shell protocol. If your compositor does not support this protocol or if you are in a non\-wayland environment then wofi must be run with \fB\-\-normal\-window\fR or it will crash. If you wish to run wofi this way you can also place \fBnormal_window=true\fR in your config file to avoid specifying the option on the command line.
.SH OPTIONS
.TP
.B \-h, \-\-help
Prints the help message and then exits.
.TP
.B \-f, \-\-fork
Forks the menu so the terminal running it can be closed.
.TP
.B \-c, \-\-conf=\fIPATH\fR
Specifies the config file to use.
.TP
.B \-s, \-\-style=\fIPATH\fR
Specifies the CSS file to use as the stylesheet.
.TP
.B \-C, \-\-color=\fIPATH\fR
Specifies the colors file to use.
.TP
.B \-d, \-\-dmenu
Runs wofi in dmenu mode.
.TP
.B \-S, \-\-show=\fIMODE\fR
Specifies the mode to run in. A list of modes can be found in \fBwofi\fR(7).
.TP
.B \-W, \-\-width=\fIWIDTH\fR
Specifies the menu width in pixels or percent of screen size, default is 50%. Pixels are used unless the number ends with a %.
.TP
.B \-H, \-\-height=\fIHEIGHT\fR
Specifies the menu height in pixels or percent of screen size, default is 40%. Pixels are used unless the number ends with a %.
.TP
.B \-p, \-\-prompt=\fIPROMPT\fR
Sets the prompt to be display in the search box, default is the name of the mode.
.TP
.B \-x, \-\-xoffset=\fIOFFSET\fR
Sets the x offset from the location in pixels, default is 0.
.TP
.B \-y, \-\-yoffset=\fIOFFSET\fR
Sets the y offset from the location in pixels, default is 0.
.TP
.B \-n, \-\-normal\-window
Runs wofi in a normal window instead of using wlr\-layer\-shell.
.TP
.B \-I, \-\-allow\-images
Allows image escape sequences to be processed and rendered.
.TP
.B \-m, \-\-allow\-markup
Allows pango markup to be processed and rendered.
.TP
.B \-k, \-\-cache\-file=\fIPATH\fR
Specifies the cache file to load/store cache, default is $XDG_CACHE_HOME/wofi\-<mode name> where <mode name> is the name of the mode, if $XDG_CACHE_HOME is not specified ~/.cache is used.
.TP
.B \-t, \-\-term=\fITERM\fR
Specifies the term to use when running a program in a terminal. This overrides the default terminal run order which is kitty, alacritty, wezterm, foot, termite, gnome\-terminal, weston\-terminal in that order.
.TP
.B \-P, \-\-password \fR[character]
Runs wofi in password mode with an optional password character to use. If no character is specified * is used by default.
.TP
.B \-e, \-\-exec\-search
Activiating a search with enter will execute the search not the first result.
.TP
.B \-b, \-\-hide\-scroll
Hides the scroll bars.
.TP
.B \-M, \-\-matching=\fIMODE\fR
Specifies the matching mode, it can be either contains, multi-contains, or fuzzy, default is contains.
.TP
.B \-i, \-\-insensitive
Enables case insensitive search.
.TP
.B \-q, \-\-parse\-search
Parses out image escapes and pango preventing them from being used for searching.
.TP
.B \-v, \-\-version
Prints the version and then exits.
.TP
.B \-l, \-\-location=\fILOCATION\fR
Specifies the location. See \fBwofi\fR(7) for more information, default is center.
.TP
.B \-a, \-\-no\-actions
Disables multiple actions for modes that support it.
.TP
.B \-D, \-\-define=\fIKEY=VALUE\fR
Sets a config option
.TP
.B \-L, \-\-lines=\fILINES\fR
Specifies the height in number of lines instead of pixels.
.TP
.B \-w, \-\-columns=\fICOLUMNS\fR
Specifies the number of columns to display, default is 1.
.TP
.B \-O, \-\-sort\-order=\fIORDER\fR
Specifies the default sort order. There are currently two orders, default and alphabetical. See \fBwofi\fR(7) for details.
.TP
.B \-G, \-\-gtk\-dark
Instructs wofi to use the dark variant of the current GTK theme, if available.
.TP
.B \-Q, \-\-search
Specifies something to search for immediately on opening
.TP
.B \-o, \-\-monitor
Sets the monitor to open on
.TP
.B \-r, \-\-pre\-display\-cmd
If set, the selectable entry won't be displayed as-is, but will instead be displayed based on the output of this command, which can be anything. Suggested to use with \fB"echo %s | some_cmd"\fR or \fB"some_cmd %s"\fR, as the string gets replaced in a printf-like fashion. This will not affect the output of wofi once a selection has been done, allowing you to display something else than the original output.
.SH CONFIGURATION
Wofi has 3 main files used for configuration. All files are completely optional.
.IP 1. 4
The config file which defaults to $XDG_CONFIG_HOME/wofi/config.
.IP 2. 4
The CSS file which defaults to $XDG_CONFIG_HOME/wofi/style.css.
.IP 3. 4
The colors file which defaults to the pywal cache $XDG_CACHE_HOME/wal/colors.
.P
All 3 of these paths can be manually specified using the respective command line flag. In the case of the last 2 they can additionally be specified in the config file.
In the event $XDG_CONFIG_HOME is not specified it defaults to ~/.config likewise if $XDG_CACHE_HOME is not specified it defaults to ~/.cache.
Information about the formats for these files can be found in
.B wofi\fR(5).

54
wofi/man/wofi.3 Normal file
View File

@@ -0,0 +1,54 @@
.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.

258
wofi/man/wofi.5 Normal file
View File

@@ -0,0 +1,258 @@
.TH wofi 5
.SH NAME
wofi \- configuration file and styling
.SH DESCRIPTION
Wofi's configuration format is very simple, consisting of key value pairs in snake case. The majority of the config options are the command line options, there are however a small handful of options only accessible via wofi's config.
Mode specific options for the built\-in modes are documented in \fBwofi\fR(7). They are placed in the config file in the format \fBmode\-example_opt=val\fR. For example dmenu has an option called \fBparse_action\fR which would be placed in the config as \fBdmenu\-parse_action=true\fR.
Anything following a # is considered to be a comment unless the # is prefixed with a \\. For this reason in order to put a backslash in the config it must be escaped as well giving \\\\.
.SH CONFIG OPTIONS
Most of the options here are the command flags as found in \fBwofi\fR(1) in snake case, however some are unique to the config.
.TP
.B style=\fIPATH\fR
Specifies the CSS file to use as the stylesheet.
.TP
.B stylesheet=\fIPATH\fR
Specifies the CSS file to use as the stylesheet. This option is NOT the same as \fBstyle\fR. Absolute paths are absolute however relative paths are relative to the wofi config folder location $XDG_CONFIG_HOME/wofi and NOT the current working directory as they are with \fBstyle\fR. They are also NOT relative to the path as specified by \fB\-\-conf\fR. This option comes from rootbar and is probably more confusing than it's worth. You should probably use \fBstyle\fR unless you're sure this is what you want.
.TP
.B color=\fIPATH\fR
Specifies the colors file to use.
.TP
.B colors=\fIPATH\fR
Specifies the colors file to use. This option is NOT the same as \fBcolor\fR. Absolute paths are absolute however relative paths are relative to the wofi config folder location $XDG_CONFIG_HOME/wofi and NOT the current working directory as they are with \fBcolor\fR. They are also NOT relative to the path as specified by \fB\-\-conf\fR. This option comes from rootbar and is probably more confusing than it's worth. You should probably use \fBcolor\fR unless you're sure this is what you want.
.TP
.B show=\fIMODE\fR
Specifies the mode to run in. A list of modes can be found in \fBwofi\fR(7).
.TP
.B mode=\fIMODE\fR
Identical to \fBshow\fR.
.TP
.B width=\fIWIDTH\fR
Specifies the menu width in pixels or percent of screen size, default is 50%. Pixels are used unless the number ends with a %.
.TP
.B height=\fIHEIGHT\fR
Specifies the menu height in pixels or percent of screen size, default is 40%. Pixels are used unless the number ends with a %.
.TP
.B prompt=\fIPROMPT\fR
Sets the prompt to be display in the search box, default is the name of the mode.
.TP
.B xoffset=\fIOFFSET\fR
Sets the x offset from the location in pixels, default is 0.
.TP
.B x=\fIOFFSET\fR
Identical to \fBxoffset\fR.
.TP
.B yoffset=\fIOFFSET\fR
Sets the y offset from the location in pixels, default is 0.
.TP
.B y=\fIOFFSET\fR
Identical to \fByoffset\fR.
.TP
.B normal_window=\fIBOOL\fR
If true runs wofi in a normal window instead of using wlr\-layer\-shell, default is false.
.TP
.B allow_images=\fIBOOL\fR
If true allows image escape sequences to be processed and rendered, default is false.
.TP
.B allow_markup=\fIBOOL\fR
If true allows pango markup to be processed and rendered, default is false.
.TP
.B cache_file=\fIPATH\fR
Specifies the cache file to load/store cache, default is $XDG_CACHE_HOME/wofi\-<mode name> where <mode name> is the name of the mode, if $XDG_CACHE_HOME is not specified ~/.cache is used.
.TP
.B term=\fITERM\fR
Specifies the term to use when running a program in a terminal. This overrides the default terminal run order which is kitty, alacritty, wezterm, foot, termite, gnome\-terminal, weston\-terminal in that order.
.TP
.B password=\fICHARACTER\fR
Runs wofi in password mode using the specified character, default is false.
.TP
.B exec_search=\fIBOOL\fR
If true activiating a search with enter will execute the search not the first result, default is false.
.TP
.B hide_scroll=\fIBOOL\fR
If true hides the scroll bars, default is false.
.TP
.B matching=\fIMODE\fR
Specifies the matching mode, it can be either contains, multi-contains, or fuzzy, default is contains.
.TP
.B insensitive=\fIBOOL\fR
If true enables case insensitive search, default is false.
.TP
.B parse_search=\fIBOOL\fR
If true parses out image escapes and pango preventing them from being used for searching, default is false.
.TP
.B location=\fILOCATION\fR
Specifies the location. See \fBwofi\fR(7) for more information, default is center.
.TP
.B no_actions=\fIBOOL\fR
If true disables multiple actions for modes that support it, default is false.
.TP
.B lines=\fILINES\fR
Specifies the height in number of lines instead of pixels.
.TP
.B columns=\fICOLUMNS\fR
Specifies the number of columns to display, default is 1.
.TP
.B sort_order=\fIORDER\fR
Specifies the default sort order. There are currently two orders, default and alphabetical. See \fBwofi\fR(7) for details.
.TP
.B gtk_dark=\fIBOOL\fR
If true, instructs wofi to use the dark variant of the current GTK theme (if available). Default is false.
.TP
.B search=\fISTRING\fR
Specifies something to search for immediately on opening
.TP
.B monitor=\fISTRING\fR
Sets the monitor to open on
.TP
.B pre_display_cmd=\fICOMMAND\fR
Specifies a printf-like string which is used on the entries prior to displaying them. This command is only used to represent the label widget's string, and won't affect the the output of the selected label.
.TP
.B orientation=\fIORIENTATION\fR
Specifies the orientation, it can be either horizontal or vertical, default is vertical.
.TP
.B halign=\fIALIGN\fR
Specifies the horizontal align for the entire scrolled area, it can be any of fill, start, end, or center, default is fill.
.TP
.B content_halign=\fIALIGN\fR
Specifies the horizontal align for the individual entries, it can be any of fill, start, end, or center, default is fill.
.TP
.B valign=\fIALIGN\fR
Specifies the vertical align for the entire scrolled area, it can be any of fill, start, end, or center, the default is orientation dependent. If vertical then it defaults to start, if horizontal it defaults to center.
.TP
.B filter_rate=\fIRATE\fR
Specifies the rate at which search results are updated in milliseconds, default is 100.
.TP
.B image_size=\fISIZE\fR
Specifies the size of images in pixels when images are enabled, default is 32.
.TP
.B key_up=\fIKEY\fR
Specifies the key to use in order to move up. Default is Up(Up arrow). See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_down=\fIKEY\fR
Specifies the key to use in order to move down. Default is Down(Down arrow). See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_left=\fIKEY\fR
Specifies the key to use in order to move left. Default is Left(Left arrow). See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_right=\fIKEY\fR
Specifies the key to use in order to move right. Default is Right(Right arrow). See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_forward=\fIKEY\fR
Specifies the key to use in order to move forward. Default is Tab. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_backward=\fIKEY\fR
Specifies the key to use in order to move backward. Default is ISO_Left_Tab(Shift+Tab). See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_submit=\fIKEY\fR
Specifies the key to use in order to submit an action. Default is Return. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_exit=\fIKEY\fR
Specifies the key to use in order to exit wofi. Default is Escape. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_pgup=\fIKEY\fR
Specifies the key to use in order to move one page up. Default is Page_Up. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_pgdn=\fIKEY\fR
Specifies the key to use in order to move one page down. Default is Page_Down. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_expand=\fIKEY\fR
Specifies the key to use in order to expand/contract multi-action entires. There is no default. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_hide_search=\fIKEY\fR
Specifies the key to use in order to hide/show the search bar. There is no default. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_copy=\fIKEY\fR
Specifies the key to use in order to copy the action text for the current entry. The default is Ctrl-c. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B key_custom_(n)=\fIKEY\fR
Allows for configuring custom exit codes. For example setting key_custom_0=Ctrl-0 will make it so if you press Ctrl-0 wofi will set its exit status to 10. This will not cause wofi to exit, it will only set its exit code for when it does. 20 of these keys are configurable numbered 0-19. The exit status used is 10+n where n is the number attached to key_custom_n. There are no defaults for these. See \fBwofi\-keys\fR(7) for the key codes.
.TP
.B line_wrap=\fIMODE\fR
Specifies the line wrap mode to use. The options are off, word, char, and word_char. Default is off.
.TP
.B global_coords=\fIBOOL\fR
Specifies whether x and y offsets should be calculated using the global compositor space instead of the current monitor. Default is false. This does not play well with locations and using it with them is not advised.
.TP
.B hide_search=\fIBOOL\fR
Specifies whether the search bar should be hidden. Default is false.
.TP
.B dynamic_lines=\fIBOOL\fR
Specifies whether wofi should be dynamically shrunk to fit the number of visible lines or if it should always stay the same size. Default is false.
.TP
.B layer=\fILAYER\fR
Specifies the layer to open on. The options are background, bottom, top, and overlay. Default is top
.TP
.B copy_exec=\fIPATH\fR
Specifies the executable to pipe copy data into. $PATH will be scanned, this is not passed to a shell and must be an executable. Default is wl-copy.
.TP
.B single_click=\fIBOOL\fR
Specifies whether or not actions should be executed on a single click or a double click. Default is false.
.TP
.B pre_display_exec=\fIBOOL\fR
This modifies the behavior of pre_display_cmd and causes the command in question to be directly executed via fork/exec rather than through the shell.
.SH CSS SELECTORS
Any GTK widget can be selected by using the name of its CSS node, these however might change with updates and are not guaranteed to stay constant. Wofi also provides certain widgets with names and classes which can be referenced from CSS to give access to the most important widgets easily. \fBwofi\fR(7) contains the current widget layout used by wofi so if you want to get into CSS directly using GTK widget names look there for info.
.TP
.B #window
.br
The name of the window itself.
.TP
.B #outer\-box
.br
The name of the box that contains everything.
.TP
.B #input
.br
The name of the search bar.
.TP
.B #scroll
.br
The name of the scrolled window containing all of the entries.
.TP
.B #inner\-box
.br
The name of the box containing all of the entries.
.TP
.B #img
.br
The name of all images in entries displayed in image mode.
.TP
.B #text
.br
The name of all the text in entries.
.TP
.B #unselected
.br
The name of all entries currently unselected. A better way of doing this is to do #entry and combine that with #entry:selected
.TP
.B #selected
.br
The name of all entries currently selected. A better way of doing this is to do #entry:selected
.TP
.B .entry
.br
The class attached to all entries. This is attached to the inside property box and is old, you probably want #entry instead
.TP
.B #entry
.br
The name of all entries.
.TP
.B #expander-box
.br
The name of all boxes shown when expanding entries with multiple actions
.SH COLORS
The colors file should be formatted as new line separated hex values. These values should be in the standard HTML format and begin with a hash. These colors will be loaded however wofi doesn't know what color should be used for what so you must reference them from your CSS.
You can reference these from your CSS by doing \-\-wofi\-color<n> where <n> is the line number \- 1. For example to reference the color on line 1 you would do \fB\-\-wofi\-color0\fR.
The colors can also be referenced by doing \-\-wofi\-rgb\-color<n> where <n> is the line number \- 1. The difference between these is the format used to replace the macro.
\-\-wofi\-color<n> is replaced with an HTML color code in the format #FFFFFF. \-\-wofi\-rgb\-color<n> is replaced with comma separated rgb values in the format 255, 255, 255. The correct usage of \-\-wofi\-rgb\-color<n> is to wrap it in rgb() or rgba(). Note that it does not return an alpha value so combining it with rgba() should be done like so \fBrgba(\-\-wofi\-rgb\-color0, 0.8)\fR. This would set the color to line 1 with an opacity of 80%.

194
wofi/man/wofi.7 Normal file
View File

@@ -0,0 +1,194 @@
.TH wofi 7
.SH NAME
wofi \- Built in modes and other features
.SH DESCRIPTION
Wofi contains several built in modes as well as a lot of other features including combi which are documented here.
The config options documented here are stripped of mode names. Mode specific config options are placed in the config file in the format \fBmode\-example_opt=val\fR. For example dmenu has an option called \fBparse_action\fR which would be placed in the config as \fBdmenu\-parse_action=true\fR.
.SH MODES
Currently wofi has 3 built in modes
.IP 1. 4
run \- searches $PATH for executables and allows them to be run by selecting them.
.IP 2. 4
drun \- searches $XDG_DATA_HOME/applications and $XDG_DATA_DIRS/applications for desktop files and allows them to be run by selecting them.
.IP 3. 4
dmenu \- reads from stdin and displays options which when selected will be output to stdout.
.P
In the event $XDG_DATA_HOME is not specified it defaults to ~/.local/share. If $XDG_DATA_DIRS is not specified it defaults to /usr/local/share:/usr/share.
Combi is not a mode however it does exist as a feature. You can use it by doing \-\-show mode1,mode2,mode3,etc. You can mix and match any number of modes however each mode can only be loaded once so doing something like \-\-show run,drun,run is not supported although I'm not sure why you'd do that in the first place.
.SH DMENU CONFIG OPTIONS
.TP
.B parse_action=\fIBOOL\fR
If true the result returned by dmenu will be stripped of image escape sequences and pango markup, default is false.
.TP
.B separator=\fICHAR\fR
The character used to separate dmenu entries, default is \\n.
.TP
.B print_line_num=\fIBOOL\fR
When an entry is selected the number of the line the entry was on is printed instead of the entry itself. This disables caching as it's fundamentally incompatible with it.
.SH RUN
In run mode holding ctrl while running an entry will cause arguments to be parsed even if always_parse_args=false. Holding shift will cause the entry to be run in a terminal.
.SH RUN CONFIG OPTIONS
.TP
.B always_parse_args=\fIBOOL\fR
If true spaces will not be treated as part of the executable name but rather as an argument separator equivalent to holding control while pressing enter, default is false.
.TP
.B show_all=\fIBOOL\fR
If true shows all the entries in path, this will show entries that have the same executable name, for example /bin/bash and /usr/bin/bash will be shown separately as bash instead of having one bash entry for the first one encountered, default is true.
.TP
.B print_command=\fIBOOL\fR
If true the executable that would be run will be printed to stdout instead of executing it, default is false.
.SH DRUN CONFIG OPTIONS
.TP
.B print_command=\fIBOOL\fR
If true the command used to launch the desktop file will be printed to stdout instead of invoking it, default is false.
.TP
.B display_generic=\fIBOOL\fR
If true then generic names will be displayed in () next to the application name, default is false.
.TP
.B disable_prime=\fIBOOL\fR
If true then wofi will ignore the PrefersNonDefaultGPU desktop variable, specifically this prevents wofi from setting DRI_PRIME, default is false.
.TP
.B print_desktop_file=\fIBOOL\fR
If true the path to the desktop file and the name of the corresponding action(if present) will be printed to stdout instead of invoking it, default is false.
.SH DRUN
When images are enabled drun mode will pull icon themes however being a GTK app it's possible you'll need to run gtk\-update\-icon\-cache to get them to apply.
.SH LOCATIONS
There are 9 possible locations which can be specified either by name or by number, the number scheme is the same as in rofi and the corresponding number is listed next to the names below, the default is center.
.IP 1. 4
center 0
.IP 2. 4
top_left 1
.IP 3. 4
top 2
.IP 4. 4
top_right 3
.IP 5. 4
right 4
.IP 6. 4
bottom_right 5
.IP 7. 4
bottom 6
.IP 8. 4
bottom_left 7
.IP 9. 4
left 8
.P
The x and y offsets are applied based on layer\-shell anchors which means an x offset can only be applied if wofi is anchored on the x axis, i.e. you can only use an x offset with the top_left, top_right, right, bottom_right, bottom_left, and left locations. center, top, and bottom can't have x offsets as they're not anchored on the x axis. Likewise y offsets can only be applied to top_left, top, top_right, bottom_right, bottom, and bottom_left locations. center, left, and right can't have y offsets because they're not anchored to the y axis. Since center can't have offsets on either as it's not anchored to any axis any x or y offset applied while using center will override the location to top_left for backwards compatibility reasons seeing as not doing so would simply ignore the offsets anyway.
.SH ORDER
There are 2 order options currently, default and alphabetical. Default means the entries are displayed in the order they are added by the mode, for all built in modes this is cached items first, followed by other entries in no specific order. Alphabetical means entries are alphabetical sorted period. These orders only affect the order when no search has been entered. Once a search is entered the order is re-arranged based on the current matching preference and this order is ignored.
.SH CACHING
Caching cannot be disabled however the cache file can be set to /dev/null to effectively disable it.
.SH WINDOW SWITCHER
Wofi does not have the ability to do window switching on its own as there is no way to do this with wayland/wlroots protocols however if you're using sway you can use swaymsg with dmenu mode to accomplish it.
The following script can be used to do window switching:
swaymsg \-t get_tree |
.br
jq \-r '.nodes[].nodes[] | if .nodes then [recurse(.nodes[])] else [] end + .floating_nodes | .[] | select(.nodes==[]) | ((.id | tostring) + " " + .name)' |
.br
wofi \-\-show dmenu | {
.br
read \-r id name
.br
swaymsg "[con_id=$id]" focus
.br
}
.SH WIDGET LAYOUT
This section is for advanced CSS which needs more control than the built in wofi CSS names/classes allow for. This widget layout is subject to change at any time and without warning so your CSS might very well break if you rely on this. Widgets have their corresponding names next to them if they have one.
.B window \- #window
.RS 4
.B box \- #outer\-box
.RS 4
.B entry \- #input
.B scrolledwindow \- #scroll
.RS 4
.B viewport
.RS 4
.B box
.RS 4
.B flowbox \- #inner\-box
.RS 4
.B flowboxchild \- #entry
.RS 4
.B .entry \- #unselected or #selected
.br
This only exists if there's ONLY 1 action. This is a WofiPropertyBox which has no CSS node and should probably not be used, the name is dependent on whether or not the entry is selected. See \fBwofi\fR(5) on #selected and #unselected for info.
.RS 4
.B image
.br
This is only present if an image is present in the entry and might occur multiple times if multiple images are present.
.B label
.br
This is only present if text is present in the entry and might occur multiple times if there are multiple text objects in a single entry.
.RE
.B expander
.br
This and its children only exist if there are multiple actions on the entry
.RS 4
.B .entry \- #unselected or #selected
.br
The main action. This is a WofiPropertyBox which has no CSS node and should probably not be used, the name is dependent on whether or not the entry is selected. See \fBwofi\fR(5) on #selected and #unselected for info.
.RS 4
.B image
.br
This is only present if an image is present in the entry and might occur multiple times if multiple images are present.
.B label
.br
This is only present if text is present in the entry and might occur multiple times if there are multiple text objects in a single entry.
.RE
.B list
.br
This contains all the secondary actions
.RS 4
.B row \- #entry
.RS 4
.B .entry \- #unselected or #selected
.br
This is a WofiPropertyBox which has no CSS node and should probably not be used, the name is dependent on whether or not the entry is selected. See \fBwofi\fR(5) on #selected and #unselected for info.
.RS 4
.B image
.br
This is only present if an image is present in the entry and might occur multiple times if multiple images are present.
.B label
.br
This is only present if text is present in the entry and might occur multiple times if there are multiple text objects in a single entry.
.RE
.RE
.RE
.RE
.RE
.RE
.RE
.RE
.B scrollbar
.RE
.RE
.RE