Update and improve Extensive code documentation article
This commit is contained in:
speedie
parent
9c4cd020e4
commit
f22e84ff9f
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue