[hackers] [dmenu] add lots of comments || Connor Lane Smith

From: <hg_AT_suckless.org>
Date: Wed, 26 Oct 2011 14:28:36 +0200 (CEST)

changeset: 456:72669cb1b8c7
user: Connor Lane Smith <cls_AT_lubutu.com>
date: Wed Oct 26 13:20:14 2011 +0100
files: dmenu.c
description:
add lots of comments


diff -r 08aadc67fc2b -r 72669cb1b8c7 dmenu.c
--- a/dmenu.c Wed Oct 26 12:14:50 2011 +0100
+++ b/dmenu.c Wed Oct 26 13:20:14 2011 +0100
_AT_@ -70,35 +70,35 @@
         int i;
 
         for(i = 1; i < argc; i++)
- /* single flags */
- if(!strcmp(argv[i], "-v")) {
+ /* these options take no arguments */
+ if(!strcmp(argv[i], "-v")) { /* prints version information */
                         puts("dmenu-"VERSION", © 2006-2011 dmenu engineers, see LICENSE for details");
                         exit(EXIT_SUCCESS);
                 }
- else if(!strcmp(argv[i], "-b"))
+ else if(!strcmp(argv[i], "-b")) /* appears at the bottom of the screen */
                         topbar = False;
- else if(!strcmp(argv[i], "-f"))
+ else if(!strcmp(argv[i], "-f")) /* grabs keyboard before reading stdin */
                         fast = True;
- else if(!strcmp(argv[i], "-i")) {
+ else if(!strcmp(argv[i], "-i")) { /* case-insensitive item matching */
                         fstrncmp = strncasecmp;
                         fstrstr = cistrstr;
                 }
                 else if(i+1 == argc)
                         usage();
- /* double flags */
- else if(!strcmp(argv[i], "-l"))
+ /* these options take one argument */
+ else if(!strcmp(argv[i], "-l")) /* number of lines in vertical list */
                         lines = atoi(argv[++i]);
- else if(!strcmp(argv[i], "-p"))
+ else if(!strcmp(argv[i], "-p")) /* adds prompt to left of input field */
                         prompt = argv[++i];
- else if(!strcmp(argv[i], "-fn"))
+ else if(!strcmp(argv[i], "-fn")) /* font or font set */
                         font = argv[++i];
- else if(!strcmp(argv[i], "-nb"))
+ else if(!strcmp(argv[i], "-nb")) /* normal background color */
                         normbgcolor = argv[++i];
- else if(!strcmp(argv[i], "-nf"))
+ else if(!strcmp(argv[i], "-nf")) /* normal foreground color */
                         normfgcolor = argv[++i];
- else if(!strcmp(argv[i], "-sb"))
+ else if(!strcmp(argv[i], "-sb")) /* selected background color */
                         selbgcolor = argv[++i];
- else if(!strcmp(argv[i], "-sf"))
+ else if(!strcmp(argv[i], "-sf")) /* selected foreground color */
                         selfgcolor = argv[++i];
                 else
                         usage();
_AT_@ -140,7 +140,7 @@
                 n = lines * bh;
         else
                 n = mw - (promptw + inputw + textw(dc, "<") + textw(dc, ">"));
-
+ /* calculate which items will begin the next page and previous page */
         for(i = 0, next = curr; next; next = next->right)
                 if((i += (lines > 0) ? bh : MIN(textw(dc, next->text), n)) > n)
                         break;
_AT_@ -174,12 +174,14 @@
                 drawtext(dc, prompt, selcol);
                 dc->x = dc->w;
         }
+ /* draw input field */
         dc->w = (lines > 0 || !matches) ? mw - dc->x : inputw;
         drawtext(dc, text, normcol);
         if((curpos = textnw(dc, text, cursor) + dc->h/2 - 2) < dc->w)
                 drawrect(dc, curpos, 2, 1, dc->h - 4, True, FG(dc, normcol));
 
         if(lines > 0) {
+ /* draw vertical list */
                 dc->w = mw - dc->x;
                 for(item = curr; item != next; item = item->right) {
                         dc->y += dc->h;
_AT_@ -187,6 +189,7 @@
                 }
         }
         else if(matches) {
+ /* draw horizontal list */
                 dc->x += inputw;
                 dc->w = textw(dc, "<");
                 if(curr->left)
_AT_@ -208,6 +211,7 @@
 grabkeyboard(void) {
         int i;
 
+ /* try to grab keyboard, we may have to wait for another process to ungrab */
         for(i = 0; i < 1000; i++) {
                 if(XGrabKeyboard(dc->dpy, DefaultRootWindow(dc->dpy), True,
                                  GrabModeAsync, GrabModeAsync, CurrentTime) == GrabSuccess)
_AT_@ -221,6 +225,7 @@
 insert(const char *str, ssize_t n) {
         if(strlen(text) + n > sizeof text - 1)
                 return;
+ /* move existing text out of the way, insert new text, and update cursor */
         memmove(&text[cursor + n], &text[cursor], sizeof text - cursor - MAX(n, 0));
         if(n > 0)
                 memcpy(&text[cursor], str, n);
_AT_@ -297,6 +302,7 @@
                         break;
                 }
                 if(next) {
+ /* jump to end of list and position items in reverse */
                         curr = matchend;
                         calcoffsets();
                         curr = prev;
_AT_@ -378,6 +384,7 @@
         Item *item, *lprefix, *lsubstr, *prefixend, *substrend;
 
         strcpy(buf, text);
+ /* separate input text into tokens to be matched individually */
         for(s = strtok(buf, " "); s; tokv[tokc-1] = s, s = strtok(NULL, " "))
                 if(++tokc > tokn && !(tokv = realloc(tokv, ++tokn * sizeof *tokv)))
                         eprintf("cannot realloc %u bytes\n", tokn * sizeof *tokv);
_AT_@ -388,8 +395,9 @@
                 for(i = 0; i < tokc; i++)
                         if(!fstrstr(item->text, tokv[i]))
                                 break;
- if(i != tokc)
+ if(i != tokc) /* not all tokens match */
                         continue;
+ /* exact matches go first, then prefixes, then substrings */
                 if(!tokc || !fstrncmp(tokv[0], item->text, len+1))
                         appenditem(item, &matches, &matchend);
                 else if(!fstrncmp(tokv[0], item->text, len))
_AT_@ -423,6 +431,7 @@
 nextrune(int inc) {
         ssize_t n;
 
+ /* return location of next utf8 rune in the given direction (+1 or -1) */
         for(n = cursor + inc; n + inc >= 0 && (text[n] & 0xc0) == 0x80; n += inc);
         return n;
 }
_AT_@ -434,6 +443,7 @@
         unsigned long dl;
         Atom da;
 
+ /* we have been given the current selection, now insert it into input */
         XGetWindowProperty(dc->dpy, win, utf8, 0, (sizeof text / 4) + 1, False,
                            utf8, &da, &di, &dl, &dl, (unsigned char **)&p);
         insert(p, (q = strchr(p, '\n')) ? q-p : (ssize_t)strlen(p));
_AT_@ -446,6 +456,7 @@
         char buf[sizeof text], *p, *maxstr = NULL;
         size_t i, max = 0, size = 0;
 
+ /* read each line from stdin and add it to the item list */
         for(i = 0; fgets(buf, sizeof buf, stdin); i++) {
                 if(i+1 >= size / sizeof *items)
                         if(!(items = realloc(items, (size += BUFSIZ))))
_AT_@ -508,7 +519,7 @@
 
         utf8 = XInternAtom(dc->dpy, "UTF8_STRING", False);
 
- /* menu geometry */
+ /* calculate menu geometry */
         bh = dc->font.height + 2;
         lines = MAX(lines, 0);
         mh = (lines + 1) * bh;
_AT_@ -521,10 +532,12 @@
 
                 XGetInputFocus(dc->dpy, &w, &di);
                 if(w != root && w != PointerRoot && w != None) {
+ /* find top-level window containing current input focus */
                         do {
                                 if(XQueryTree(dc->dpy, (pw = w), &dw, &w, &dws, &du) && dws)
                                         XFree(dws);
                         } while(w != root && w != pw);
+ /* find xinerama screen with which the window intersects most */
                         if(XGetWindowAttributes(dc->dpy, pw, &wa))
                                 for(j = 0; j < n; j++)
                                         if((a = INTERSECT(wa.x, wa.y, wa.width, wa.height, info[j])) > area) {
_AT_@ -532,10 +545,12 @@
                                                 i = j;
                                         }
                 }
+ /* no focused window is on screen, so use pointer location instead */
                 if(!area && XQueryPointer(dc->dpy, root, &dw, &dw, &x, &y, &di, &di, &du))
                         for(i = 0; i < n; i++)
                                 if(INTERSECT(x, y, 1, 1, info[i]))
                                         break;
+
                 x = info[i].x_org;
                 y = info[i].y_org + (topbar ? 0 : info[i].height - mh);
                 mw = info[i].width;
_AT_@ -552,7 +567,7 @@
         inputw = MIN(inputw, mw/3);
         match();
 
- /* menu window */
+ /* create menu window */
         swa.override_redirect = True;
         swa.background_pixmap = ParentRelative;
         swa.event_mask = ExposureMask | KeyPressMask | VisibilityChangeMask;
_AT_@ -561,7 +576,7 @@
                             DefaultVisual(dc->dpy, screen),
                             CWOverrideRedirect | CWBackPixmap | CWEventMask, &swa);
 
- /* input methods */
+ /* open input methods */
         xim = XOpenIM(dc->dpy, NULL, NULL, NULL);
         xic = XCreateIC(xim, XNInputStyle, XIMPreeditNothing | XIMStatusNothing,
                         XNClientWindow, win, XNFocusWindow, win, NULL);
Received on Wed Oct 26 2011 - 14:28:36 CEST

This archive was generated by hypermail 2.3.0 : Wed Oct 26 2011 - 14:36:05 CEST