From f22e84ff9f4e584655ae5802fb85c14efc4726bc Mon Sep 17 00:00:00 2001 From: speedie Date: Sat, 24 Jun 2023 18:44:35 +0200 Subject: [PATCH] Update and improve Extensive code documentation article --- pages/Extensive code documentation.md | 158 ++++++++++++++++++++------ 1 file changed, 126 insertions(+), 32 deletions(-) diff --git a/pages/Extensive code documentation.md b/pages/Extensive code documentation.md index 477f9a1..03ec977 100755 --- a/pages/Extensive code documentation.md +++ b/pages/Extensive code documentation.md @@ -6,7 +6,104 @@ 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. -- Position and width/height variables +## 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 +│   ├── argv.h - Contains functions for parsing arguments +│   ├── colors.h - Contains a textcolors array +│   ├── conf +│   │   ├── config.c - Contains functions for reading spmenu.conf +│   │   └── config.h - Declares functions for reading spmenu.conf +│   ├── define.c - Contains some macros +│   ├── 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 +│   ├── history.c - Contains functions for handling the history buffer +│   ├── history.h - Declares functions for handling the history buffer +│   ├── img.c - Contains functions for drawing and handling images +│   ├── img.h - Declares functions for drawing and handling images +│   ├── keybinds.h - Contains keybind arrays for X11 and Wayland +│   ├── main.c - Contains core functions like ecalloc, sp_strncpy and die +│   ├── main.h - Declares core functions like ecalloc, sp_strncpy and die +│   ├── match.c - Contains functions for matching items using input text +│   ├── match.h - Declares functions for matching items using input text +│   ├── mouse.h - Contains mouse arrays for X11 and Wayland +│   ├── options.h - Contains the default options for spmenu +│   ├── rtl.c - Contains functions for right-to-left language support using GNU Fribidi +│   ├── rtl.h - Declares 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 +│   ├── theme +│   │   ├── theme.c - Contains functions for reading theme.conf +│   │   └── theme.h - Declares functions for reading theme.conf +│   ├── 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 +│   ├── def.h - Defines a few macros used for keybinds +│   ├── 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` @@ -20,11 +117,11 @@ would be greatly appreciated. - `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 `drw_text` use this. + - 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 `drw_text` use this. + - 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` @@ -40,7 +137,7 @@ would be greatly appreciated. - `ey` - Wayland version of `ev.y` (See `libs/wl/wayland.c`) - `w` - - Width of something, this is passed to `drw_text()` for example, but you may + - 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 @@ -105,71 +202,68 @@ would be greatly appreciated. - Cursor/caret position. When text is added to the input, the width of that text is added to this. -- Cairo functions +## Cairo functions -Most of these are in `libs/libdrw/drw.c` and `libs/libdrw/drw.h` +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 +## Drawable abstraction functions -Most of these are in `libs/libdrw/drw.c` and `libs/libdrw/drw.h`. +Most of these are in `libs/draw/draw.c` and `libs/draw/draw.h`. -- `drw_create_x11(Display *dpy, int screen, Window win, unsigned int w, +- `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`, `Drw`. Think of + - This function creates a drawable from `Display *dpy`, `Draw_t`. Think of it as a canvas. -- `drw_create_wl(int protocol);` +- `draw_create_wl(int protocol);` - NOTE: Wayland specific. - - This function creates a Cairo drawable and `Drw *` that we can then + - This function creates a Cairo drawable and `Draw_t *` that we can then draw rectangles and text on. -- `drw_resize(Drw *drw, unsigned int w, unsigned int h)` +- `draw_resize(Draw_t *draw, unsigned int w, unsigned int h)` - This function resizes the drawable to the dimensions passed as arguments (`w`, `h`). -- `drw_free(Drw *drw);` +- `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/libdrw/drw.c` and `libs/libdrw/drw.h`. +Most of these are in `libs/draw/draw.c` and `libs/draw/draw.h`. -- `drw_font_create(Drw* drw, char *font[], size_t fontcount);` +- `draw_font_create(Draw_t* draw, char *font[], size_t fontcount);` - This function will return a font Cairo and Pango can use. -- `drw_font_free(Fnt *set);` +- `draw_font_free(Fnt *set);` - This function will free the font from memory. -- `drw_fontset_getwidth_clamp(Drw *drw, const char *text, unsigned int n, Bool markup);` +- `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. -- `drw_font_getwidth(Drw *drw, const char *text, Bool markup);` +- `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. -- `drw_font_getexts(Fnt *font, const char *text, unsigned int len, unsigned +- `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. -- Cursor abstraction functions +## Drawing functions -- `drw_cur_create(Drw *drw, int shape);` - - This function creates and returns a cursor. -- `drw_cur_free(Drw *drw, Cur *cursor);` - - This function will free the cursor from memory. - -- Drawing functions - -- `drw_rect(Drw *drw, int x, int y, unsigned int w, unsigned int h, int filled +- `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. -- `drw_text(Drw *drw, int x, int y, unsigned int w, unsigned int h, unsigned +- `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 +## Map functions -- `drw_map(Drw *drw, Window win, int x, int y, unsigned int w, unsigned int h);` +- `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. +