260 lines
12 KiB
Markdown
Executable file
260 lines
12 KiB
Markdown
Executable file
# 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.
|