From: Christian Heller <c.heller@plomlompom.de>
Date: Mon, 29 Jul 2013 18:09:12 +0000 (+0200)
Subject: Applied new formatting and documentation requirements to keybindings library.
X-Git-Tag: tce~1120
X-Git-Url: https://plomlompom.com/repos/%22https:/validator.w3.org/condition_titles?a=commitdiff_plain;h=e11aa749989942b66dfc4fd7ccb72c2c8e767332;p=plomrogue

Applied new formatting and documentation requirements to keybindings library.
---

diff --git a/src/keybindings.c b/src/keybindings.c
index 2f27da9..3809416 100644
--- a/src/keybindings.c
+++ b/src/keybindings.c
@@ -1,117 +1,193 @@
+/* keybindings.c */
+
+
+
 #include "keybindings.h"
-#include <stdint.h>
-#include <stdlib.h>
-#include <ncurses.h>
-#include <string.h>
-#include "windows.h"
-#include "misc.h"
-#include "main.h"
-
-void init_keybindings(struct World * world) {
-// Initialize keybindings from file "keybindings".
-  FILE * file = fopen("keybindings", "r");
-  uint16_t lines, linemax;
-  textfile_sizes (file, &linemax, &lines);
-  struct KeyBinding * keybindings = malloc(lines * sizeof(struct KeyBinding));
-  char * command = malloc(linemax);
-  uint16_t commcount = 0;
-  char * cmdptr;
-  while (fgets(command, linemax, file)) {
-    keybindings[commcount].key = atoi(command);
-    cmdptr = strchr(command, ' ') + 1;
-    keybindings[commcount].name = malloc(strlen(cmdptr));
-    memcpy(keybindings[commcount].name, cmdptr, strlen(cmdptr) - 1);
-    keybindings[commcount].name[strlen(cmdptr) - 1] = '\0';
-    commcount++; }
-  free(command);
-  fclose(file);
-  struct KeysWinData * keyswindata = malloc(sizeof(struct KeysWinData));
-  keyswindata->max = lines - 1;
-  keyswindata->select = 0;
-  keyswindata->edit = 0;
-  world->keybindings = keybindings;
-  world->keyswindata = keyswindata; }
-
-void save_keybindings(struct World * world) {
-// Write keybindings to keybindings file.
-  struct KeysWinData * keyswindata = (struct KeysWinData *) world->keyswindata;
-  struct KeyBinding * keybindings = world->keybindings;
-  FILE * file = fopen("keybindings", "w");
-  uint16_t linemax = 0;
-  uint16_t i;
-  for (i = 0; i <= keyswindata->max; i++)
-    if (strlen(keybindings[i].name) > linemax)
-      linemax = strlen(keybindings[i].name);
-  linemax = linemax + 6;                                // + 6 = + 3 digits + whitespace + newline + null byte
-  char * line = malloc(linemax);
-  for (i = 0; i <= keyswindata->max; i++) {
-    snprintf(line, linemax, "%d %s\n", keybindings[i].key, keybindings[i].name);
-    fwrite(line, sizeof(char), strlen(line), file); }
-  free(line);
-  fclose(file); }
-
-uint16_t get_action_key (struct KeyBinding * keybindings, char * name) {
-// Return key matching name in keybindings.
-  uint16_t i = 0;
-  while (strcmp(keybindings[i].name, name) )
-    i++;
-  return keybindings[i].key; }
-
-char * get_keyname(uint16_t keycode) {
-// Translate some keycodes to readable names of max 9 chars.
-  char * keyname;
-  keyname = malloc(15);
-  if (32 < keycode && keycode < 127)
-    sprintf(keyname, "%c", keycode);
-  else if (keycode == 9)
-    sprintf(keyname, "TAB");
-  else if (keycode == 10)
-    sprintf(keyname, "RETURN");
-  else if (keycode == 27)
-    sprintf(keyname, "ESCAPE");
-  else if (keycode == 32)
-    sprintf(keyname, "SPACE");
-  else if (keycode == KEY_UP)
-    sprintf(keyname, "UP");
-  else if (keycode == KEY_DOWN)
-    sprintf(keyname, "DOWN");
-  else if (keycode == KEY_LEFT)
-    sprintf(keyname, "LEFT");
-  else if (keycode == KEY_RIGHT)
-    sprintf(keyname, "RIGHT");
-  else if (keycode == KEY_HOME)
-    sprintf(keyname, "HOME");
-  else if (keycode == KEY_BACKSPACE)
-    sprintf(keyname, "BACKSPACE");
-  else if (keycode >= KEY_F0 && keycode <= KEY_F(63)) {
-    uint16_t f = keycode - KEY_F0;
-    sprintf(keyname, "F%d", f); }
-  else if (keycode == KEY_DC)
-    sprintf(keyname, "DELETE");
-  else if (keycode == KEY_IC)
-    sprintf(keyname, "INSERT");
-  else if (keycode == KEY_NPAGE)
-    sprintf(keyname, "NEXT PAGE");
-  else if (keycode == KEY_PPAGE)
-    sprintf(keyname, "PREV PAGE");
-  else if (keycode == KEY_END)
-    sprintf(keyname, "END");
-  else
-    sprintf(keyname, "(unknown)");
-  return keyname;  }
-
-void keyswin_mod_key (struct World * world, struct WinMeta * win_meta) {
-// In keybindings window, mark selection modifiable, modify key. Ensure max of three digits in key code field.
-  world->keyswindata->edit = 1;
-  draw_all_wins (win_meta);
-  int key = getch();
-  if (key < 1000)
-    world->keybindings[world->keyswindata->select].key = key;
-  world->keyswindata->edit = 0; }
-
-void keyswin_move_selection (struct World * world, char dir) {
-// In keybindings window, move selection upwards or downwards (if within limits of list length).
-  if ('u' == dir && world->keyswindata->select > 0)
-    world->keyswindata->select--;
-  else if ('d' == dir && world->keyswindata->select < world->keyswindata->max)
-    world->keyswindata->select++; }
+#include <stdlib.h>  /* for malloc(), free(), atoi() */
+#include <stdint.h>  /* for uint16_t */
+#include <ncurses.h> /* for keycode defines in get_keyname() */
+#include <string.h>  /* for strchr(), strlen(), strcmp(), memcpy()*/
+#include "windows.h" /* for draw_all_wins() and WinMeta struct */
+#include "misc.h"    /* for texfile_sizes() */
+#include "main.h"    /* for World struct */
+
+
+
+extern void init_keybindings(struct World * world)
+{
+    FILE * file = fopen("keybindings", "r");
+    uint16_t lines, linemax;
+    textfile_sizes(file, &linemax, &lines);
+    struct KeyBinding * keybindings = malloc(lines * sizeof(struct KeyBinding));
+    char * command = malloc(linemax);
+    uint16_t commcount = 0;
+    char * cmdptr;
+    while (fgets(command, linemax, file))
+    {
+        keybindings[commcount].key = atoi(command);
+        cmdptr = strchr(command, ' ') + 1;
+        keybindings[commcount].name = malloc(strlen(cmdptr));
+        memcpy(keybindings[commcount].name, cmdptr, strlen(cmdptr) - 1);
+        keybindings[commcount].name[strlen(cmdptr) - 1] = '\0';
+        commcount++;
+    }
+    free(command);
+    fclose(file);
+    struct KeysWinData * keyswindata = malloc(sizeof(struct KeysWinData));
+    keyswindata->max = lines - 1;
+    keyswindata->select = 0;
+    keyswindata->edit = 0;
+    world->keybindings = keybindings;
+    world->keyswindata = keyswindata;
+}
+
+
+
+extern void save_keybindings(struct World * world)
+{
+    struct KeysWinData * keyswindata = (struct KeysWinData *)
+                                       world->keyswindata;
+    struct KeyBinding * keybindings = world->keybindings;
+    FILE * file = fopen("keybindings", "w");
+    uint16_t linemax = 0;
+    uint16_t i;
+    for (i = 0; i <= keyswindata->max; i++)
+    {
+        if (strlen(keybindings[i].name) > linemax)
+        {
+            linemax = strlen(keybindings[i].name);
+        }
+    }
+    linemax = linemax + 6;         /* + 6 = + 3 digits + whitespace + \n + \0 */
+    char * line = malloc(linemax);
+    for (i = 0; i <= keyswindata->max; i++)
+    {
+        snprintf(line, linemax,
+                 "%d %s\n", keybindings[i].key, keybindings[i].name);
+        fwrite(line, sizeof(char), strlen(line), file);
+    }
+    free(line);
+    fclose(file);
+}
+
+
+
+extern uint16_t get_action_key(struct KeyBinding * keybindings, char * name)
+{
+    uint16_t i = 0;
+    while (strcmp(keybindings[i].name, name) )
+    {
+        i++;
+    }
+    return keybindings[i].key;
+}
+
+
+
+extern char * get_keyname(uint16_t keycode)
+{
+    char * keyname;
+    keyname = malloc(15);
+    if (32 < keycode && keycode < 127)
+    {
+        sprintf(keyname, "%c", keycode);
+    }
+    else if (keycode == 9)              /* TODO: Find a way more elegant than */
+    {                                   /*       hardcoding all of this?      */
+        sprintf(keyname, "TAB");
+    }
+    else if (keycode == 10)
+    {
+        sprintf(keyname, "RETURN");
+    }
+    else if (keycode == 27)
+    {
+        sprintf(keyname, "ESCAPE");
+    }
+    else if (keycode == 32)
+    {
+        sprintf(keyname, "SPACE");
+    }
+    else if (keycode == KEY_UP)
+    {
+        sprintf(keyname, "UP");
+    }
+    else if (keycode == KEY_DOWN)
+    {
+        sprintf(keyname, "DOWN");
+    }
+    else if (keycode == KEY_LEFT)
+    {
+        sprintf(keyname, "LEFT");
+    }
+    else if (keycode == KEY_RIGHT)
+    {
+        sprintf(keyname, "RIGHT");
+    }
+    else if (keycode == KEY_HOME)
+    {
+        sprintf(keyname, "HOME");
+    }
+    else if (keycode == KEY_BACKSPACE)
+    {
+        sprintf(keyname, "BACKSPACE");
+    }
+    else if (keycode >= KEY_F0 && keycode <= KEY_F(63))
+    {
+        uint16_t f = keycode - KEY_F0;
+        sprintf(keyname, "F%d", f);
+    }
+    else if (keycode == KEY_DC)
+    {
+        sprintf(keyname, "DELETE");
+    }
+    else if (keycode == KEY_IC)
+    {
+        sprintf(keyname, "INSERT");
+    }
+    else if (keycode == KEY_NPAGE)
+    {
+        sprintf(keyname, "NEXT PAGE");
+    }
+    else if (keycode == KEY_PPAGE)
+    {
+        sprintf(keyname, "PREV PAGE");
+    }
+    else if (keycode == KEY_END)
+    {
+        sprintf(keyname, "END");
+    }
+    else
+    {
+        sprintf(keyname, "(unknown)");
+    }
+    return keyname;
+}
+
+
+
+extern void keyswin_mod_key(struct World * world, struct WinMeta * win_meta)
+{
+    world->keyswindata->edit = 1;
+    draw_all_wins (win_meta);
+    int key = getch();
+    if (key < 1000)
+    {
+        world->keybindings[world->keyswindata->select].key = key;
+    }
+    world->keyswindata->edit = 0;
+}
+
+
+
+extern void keyswin_move_selection(struct World * world, char dir)
+{
+    if      ('u' == dir && world->keyswindata->select > 0)
+    {
+        world->keyswindata->select--;
+    }
+    else if ('d' == dir && world->keyswindata->select < world->keyswindata->max)
+    {
+        world->keyswindata->select++;
+    }
+}
diff --git a/src/keybindings.h b/src/keybindings.h
index 4cdcd5a..9c22965 100644
--- a/src/keybindings.h
+++ b/src/keybindings.h
@@ -1,25 +1,66 @@
+/* keybindings.h
+ *
+ * Retrieval and storage of keybindings.
+ */
+
 #ifndef KEYBINDINGS_H
 #define KEYBINDINGS_H
 
-#include <stdint.h>
 
+
+#include <stdint.h> /* for uint16_t */
 struct World;
 struct WinMeta;
 
-struct KeyBinding {
-  char * name;
-  uint16_t key; };
-
-struct KeysWinData {
-  uint16_t max;
-  char edit;
-  uint16_t select; };
-
-extern void init_keybindings(struct World *);
-extern void save_keybindings(struct World *);
-extern uint16_t get_action_key (struct KeyBinding *, char *);
-extern char * get_keyname(uint16_t);
-extern void keyswin_mod_key (struct World *, struct WinMeta *);
-extern void keyswin_move_selection (struct World *, char);
+
+
+/* Individual keybinding. */
+struct KeyBinding
+{
+  char * name;  /* name of functionality bound to keycode */
+  uint16_t key; /* keycode */
+};
+
+
+
+/* Metadata for the keybindings plurality and their editing window. */
+struct KeysWinData
+{
+  uint16_t max;    /* ? */
+  char edit;       /* ? */
+  uint16_t select; /* ? */
+};
+
+
+
+/* Read keybindings data from / write them to the file "keybindings". */
+extern void init_keybindings(struct World * world);
+extern void save_keybindings(struct World * world);
+
+
+
+/* Return keycode matching a key (functionality) name. */
+extern uint16_t get_action_key(struct KeyBinding * keybindings, char * name);
+
+
+
+/* Translate keycode to readable names of max 9 chars where possible. */
+extern char * get_keyname(uint16_t keycode);
+
+
+
+/* Mark selection in keybindings window modifiable, get user input to modify
+ * key. Ensure there are max. three digits in the keycode ASCII representation.
+ */
+extern void keyswin_mod_key(struct World * world, struct WinMeta * win_meta);
+
+
+
+/* Move selection in keybinding window upwards ("dir" = "u") or downwards ("dir"
+ * = "d") within the limits of the keybindings list length.
+ */
+extern void keyswin_move_selection(struct World * world, char dir);
+
+
 
 #endif