# Extensive code documentation

Some of spmenu's code documented. If you want to hack on the project, this
should be useful. Note that these may be renamed in the future to make the
codebase easier to understand and make changes to. Also note that this is
**definitely not** a complete list. Contributions that help expand this
would be greatly appreciated.

## File tree

```Text
.
├── docs
│   ├── docs.md - Markdown documentation for spmenu, compiled into a man page
│   ├── example.Xresources - Example .Xresources file
│   ├── run-docs.md - Markdown documentation for spmenu_run
│   ├── spmenu.conf - Default configuration file for spmenu
│   ├── spmenu_desktop.desktop - .desktop entry for spmenu_run -d
│   ├── spmenu_filemanager.desktop - .desktop entry for spmenu_run -fm
│   ├── spmenu_run.desktop - .desktop entry for spmenu_run -x
│   └── spmenu.svg - Vector logo for spmenu
├── libs
│   ├── arg.c - Contains Arg *arg functions
│   ├── arg.h - Declares Arg *arg functions
│   ├── argv.c - Contains functions for parsing arguments
│   ├── conf
│   │   ├── config.c - Contains functions for reading spmenu.conf
│   │   └── config.h - Declares functions for reading spmenu.conf
│   ├── draw
│   │   ├── draw.c - Contains functions for drawing with Cairo and Pango
│   │   └── draw.h - Declares functions for drawing with Cairo and Pango
│   ├── draw.c - Contains functions for drawing different menu elements
│   ├── draw.h - Declares functions for drawing different menu elements
│   ├── fifo.c - Contains functions for the FIFO
│   ├── history.c - Contains functions for handling the history buffer
│   ├── icon.c - Contains functions for drawing and handling icons
│   ├── img.c - Contains functions for drawing and handling images
│   ├── main.c - Contains core functions like ecalloc, sp_strncpy and die
│   ├── match.c - Contains functions for matching items using input text
│   ├── options.h - Contains the default options for spmenu
│   ├── regex
│   │   ├── regex.c - Contains tiny-regex-c
│   │   └── regex.h - Declares tiny-regex-c
│   ├── rtl.c - Contains functions for right-to-left language support using GNU Fribidi
│   ├── schemes.c - Contains functions for SGR color support and alpha
│   ├── schemes.h - Declares functions for SGR color support and alpha
│   ├── sort.c - Contains functions for sorting items
│   ├── sort.h - Declares functions for sorting items
│   ├── stream.c - Contains functions for reading items from file/stdin
│   ├── stream.h - Declares functions for reading items from file/stdin
│   ├── wl
│   │   ├── inc.c - Includes C code for Wayland
│   │   ├── inc.h - Includes C headers for Wayland
│   │   ├── init.c - Contains functions for creating the Wayland window
│   │   ├── init.h - Declares functions for creating the Wayland window
│   │   ├── shm.c - Creates a shared memory buffer used to draw to the Wayland window.
│   │   ├── wayland.c - Includes abstraction functions for handling Wayland
│   │   └── wayland.h - Declares abstraction functions for handling Wayland
│   └── x11
│       ├── client.c - Contains functions for handling the X11 window
│       ├── client.h - Declares functions for handling the X11 window
│       ├── clipboard.c - Contains functions for handling the X11 clipboard
│       ├── clipboard.h - Declares functions for handling the X11 clipboard
│       ├── event.c - Contains functions for handling X11 events
│       ├── event.h - Declares functions for handling X11 events
│       ├── focus.c - Contains functions for handling focus
│       ├── focus.h - Declares functions for handling focus
│       ├── inc.c - Includes C code for X11
│       ├── inc.h - Includes C headers for X11
│       ├── init.c - Contains functions for creating the X11 window
│       ├── init.h - Declares functions for creating the X11 window
│       ├── key.c - Contains functions for handling keybinds
│       ├── key.h - Declares functions for handling keybinds
│       ├── lib.h - Includes Xlib and other X11 libraries
│       ├── mouse.c - Contains functions for handling mouse clicks
│       ├── mouse.h - Declares functions for handling mouse clicks
│       ├── xim.c - Contains functions for handling XIM
│       ├── xim.h - Declares functions for handling XIM
│       ├── xrdb.c - Contains functions for handling the xrdb
│       ├── xrdb.h - Declares functions for handling the xrdb
│       └── xresources.h - Contains an array of valid .Xresources values
├── LICENSE - License for spmenu
├── meson.build - Meson build
├── meson.options - Meson options
├── PKGBUILD - Arch PKGBUILD
├── protocols
│   ├── generate.sh - Runs scripts/spmenu_make headers
│   ├── wlr-layer-shell-unstable-v1.xml - wlr-layer-shell protocol
│   ├── xdg-output-unstable-v1.xml - xdg-output
│   └── xdg-shell.xml - xdg-shell
├── README.md - README for spmenu
├── spmenu.1 - man page for spmenu
├── spmenu.c - Main C code for spmenu
└── spmenu_run.1 - man page for spmenu_run
```

## Position and width/height variables

- `bh`
  - Menu height divided by lines gets you `bh`. The name comes from dwm's `bh`
  meaning 'bar height'. This is the height of each item in the list.
- `mh`
  - Menu height (or height of the window)
  - Use `resizeclient()` to resize to this.
- `mw`
  - Menu width (or width of the window)
  - Use `resizeclient()` to resize to this.
  - `2 * borderwidth` is removed from `mw` (2* because we have two sides)
  - `2 * sp` is removed from `mw` (2* because we have two sides)
- `x`
  - X position, functions like `draw_text` use this.
  - If you set this in bar drawing functions, you must apply the same
  to `buttonpress()`, otherwise clicks will be offset.
- `y`
  - Y position, functions like `draw_text` use this.
  - If you set this in bar drawing functions, you must apply the same
  to `buttonpress()`, otherwise clicks will be offset.
- `ev.x`
  - NOTE: X11 only
  - X position where you clicked. This is used in the `buttonpress()` function
  to check where you clicked.
- `ev.y`
  - NOTE: X11 only
  - Y position where you clicked. This is used in the `buttonpress()` function
  to check where you clicked.
- `ex`
  - Wayland version of `ev.x` (See `libs/wl/wayland.c`)
- `ey`
  - Wayland version of `ev.y` (See `libs/wl/wayland.c`)
- `w`
  - Width of something, this is passed to `draw_text()` for example, but you may
  override this.
- `plw`
  - This is the width of the powerline arrow. It must be added on in
  the `buttonpress()` and draw functions.
- `vp`
  - Vertical padding, this is initially added on in the `create_window()` function.
- `sp`
  - Horizontal padding, this is initially added on in the `create_window()` function.
- `promptw`
  - Width of the prompt text, this is going to be the same as `TEXTW(prompt)`.
- `inputw`
  - Width of the input text.
- `fh`
  - Font height. Used to calculate the height of the cursor. See `drawcaret()`.
- `menuposition`
  - Integer the user is meant to configure. If it's set to `0`, spmenu will be
  put on the bottom of the screen. If it's set to `1` it will be put on the
  top of the screen. If it's `2` it will be put in the center of the screen.
- `wa.width`
  - NOTE: X11 only
  - Window width with Xinerama, `wa` is `XWindowAttributes`.
- `wa.height`
  - NOTE: X11 only
  - Window height with Xinerama, `wa` is `XWindowAttributes`.
- `state.width`
  - Wayland `wa.width`.
- `state.height`
  - Wayland `wa.height`.
- `imageheight`
  - Image height, This is **not** the height of the image, it is the height
  that the image will be scaled to fit.
- `imagewidth`
  - Image width, This is **not** the width of the image, it is the width
  that the image will be scaled to fit.
- `imagegaps`
  - Image gaps, this is extra space added around the image.
- `imageh`
  - Usually the same as `imageheight`. This is what `imageheight` is initially
  set to.
- `imagew`
  - Usually the same as `imagewidth`. This is what `imagewidth` is initially
  set to.
- `imageg`
  - Usually the same as `imagegaps`. This is what `imagegaps` is initially set to.
- `longestedge`
  - As the name implies, it is the longest (highest value) of `imageheight` and `imagewidth`.
- `numberWidth`
  - Integer set in some functions, it is simply `TEXTW(numbers)` if the match
  count isn't hidden.
- `modeWidth`
  - Integer set in some functions, it is simply `TEXTW(modetext)` if the mode
  indicator isn't hidden.
- `larrowWidth`
  - Integer set in some functions, it is simply `TEXTW(leftarrow)` if the left
  arrow isn't hidden.
- `rarrowWidth`
  - Integer set in some functions, it is simply `TEXTW(rightarrow)` if the right
  arrow isn't hidden.
- `powerlinewidth`
  - Integer set in some functions, it is simply `plw / 2` if powerlines are enabled.
- `curpos`
  - Cursor/caret position. When text is added to the input, the width of that text
  is added to this.

## Cairo functions

Most of these are in `libs/draw/draw.c` and `libs/draw/draw.h`

- `cairo_set_source_hex(cairo_t* cr, const char *col, int alpha);`
  - This function converts hex #RRGGBB colors into RGB format and sets the
  cairo color to the color.

## Drawable abstraction functions

Most of these are in `libs/draw/draw.c` and `libs/draw/draw.h`.

- `draw_create_x11(Display *dpy, int screen, Window win, unsigned int w,
unsigned int h, Visual *visual, unsigned int depth, Colormap cmap);`
  - NOTE: X11 specific.
  - This function creates a drawable from `Display *dpy`, `Draw_t`. Think of
  it as a canvas.
- `draw_create_wl(int protocol);`
  - NOTE: Wayland specific.
  - This function creates a Cairo drawable and `Draw_t *` that we can then
  draw rectangles and text on.
- `draw_resize(Draw_t *draw, unsigned int w, unsigned int h)`
  - This function resizes the drawable to the dimensions passed as
  arguments (`w`, `h`).
- `draw_free(Draw_t *draw);`
  - This function will free the drawable from memory. It is *usually* called in
  cleanup functions like `cleanup()` so most of the time you don't need to use this.

- Font abstraction functions

Most of these are in `libs/draw/draw.c` and `libs/draw/draw.h`.

- `draw_font_create(Draw_t* draw, char *font[], size_t fontcount);`
  - This function will return a font Cairo and Pango can use.
- `draw_font_free(Fnt *set);`
  - This function will free the font from memory.
- `draw_fontset_getwidth_clamp(Draw_t *draw, const char *text, unsigned int n,
Bool markup);`
  - This function returns the smallest value out of the passed argument `n`
  and the length of the text drawn. The text is not actually drawn though.
- `draw_font_getwidth(Draw_t *draw, const char *text, Bool markup);`
  - This function returns the width of drawn text. The text is not actually
  drawn though.
- `draw_font_getexts(Fnt *font, const char *text, unsigned int len, unsigned
  int *w, unsigned int *h, Bool markup);`
  - This function returns the length of the text with the used font.

## Drawing functions

- `draw_rect(Draw_t *draw, int x, int y, unsigned int w, unsigned int h, int filled
, int invert);`
  - Draws a simple rectangle. Used in other functions to create more useful
  shapes, such as a cursor.
- `draw_text(Draw_t *draw, int x, int y, unsigned int w, unsigned int h, unsigned
int lpad, const char *text, int invert, Bool markup);`
  - Draws text on the drawable using the font created. `const char *text`
  contains the text itself.

## Map functions

- `draw_map(Draw_t *draw, Window win, int x, int y, unsigned int w, unsigned
int h);`
  - Maps the drawable. (makes it visible)
  - X11 only, drawmenu() function does the mapping for Wayland.