From 3ba7cfd701d99b4b1fe1dd7eecd02d01c1dee74c Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 12 Aug 2008 14:44:03 +0930 Subject: Adding some explanatory comments. --- setxkbmap.c | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 9 deletions(-) diff --git a/setxkbmap.c b/setxkbmap.c index 6368f65..4f65454 100644 --- a/setxkbmap.c +++ b/setxkbmap.c @@ -57,17 +57,21 @@ #define DFLT_XKB_MODEL "pc105" #endif +/* Values used in svSrc to state how a value was obtained. The order of these + * is important, the bigger the higher the priority. + * e.g. FROM_CONFIG overrides FROM_SERVER */ #define UNDEFINED 0 -#define FROM_SERVER 1 -#define FROM_RULES 2 -#define FROM_CONFIG 3 -#define FROM_CMD_LINE 4 +#define FROM_SERVER 1 /* retrieved from server at runtime */ +#define FROM_RULES 2 /* xkb rules file */ +#define FROM_CONFIG 3 /* command-line specified config file */ +#define FROM_CMD_LINE 4 /* specified at the cmdline */ #define NUM_SOURCES 5 -#define RULES_NDX 0 -#define CONFIG_NDX 1 -#define DISPLAY_NDX 2 -#define LOCALE_NDX 3 +/* Indices used into svSrc, svNValue */ +#define RULES_NDX 0 /* rules file */ +#define CONFIG_NDX 1 /* config file (if used) */ +#define DISPLAY_NDX 2 /* X display name */ +#define LOCALE_NDX 3 /* machine's locale */ #define MODEL_NDX 4 #define LAYOUT_NDX 5 #define VARIANT_NDX 6 @@ -86,17 +90,33 @@ int verbose = 5; Display *dpy; +/** + * human-readable versions of FROM_CONFIG, FROM_SERVER, etc. Used for error + * reporting. + */ char *srcName[NUM_SOURCES] = { "undefined", "X server", "rules file", "config file", "command line" }; +/** + * human-readable versions for RULES_NDX, CONFIG_NDX, etc. Used for error + * reporting. + */ char *svName[NUM_STRING_VALS] = { "rules file", "config file", "X display", "locale", "keyboard model", "keyboard layout", "layout variant", "keycodes", "types", "compatibility map", "symbols", "geometry", "keymap" }; +/** + * Holds the source for each of RULES, CONFIG, DISPLAY, etc. + * i.e. if svSrc[LAYOUT_NDX] == FROM_SERVER, then the layout has been fetched + * from the server. + */ int svSrc[NUM_STRING_VALS]; +/** + * Holds the value for each of RULES, CONFIG, DISPLAY, etc. + */ char *svValue[NUM_STRING_VALS]; XkbConfigRtrnRec cfgResult; @@ -267,6 +287,13 @@ dumpNames(Bool wantRules, Bool wantCNames) /***====================================================================***/ +/** + * Set the given string (obtained from src) in the svValue/svSrc globals. + * If the given item is already set, it is overridden if the original source + * is less significant than the given one. + * + * @param which What value is it (one of RULES_NDX, CONFIG_NDX, ...) + */ void trySetString(int which, char *newVal, int src) { @@ -333,6 +360,11 @@ setOptString(int *arg, int argc, char **argv, int which, int src) /***====================================================================***/ +/** + * Parse commandline arguments. + * Return True on success or False if an unrecognized option has been + * specified. + */ int parseArgs(int argc, char **argv) { @@ -347,6 +379,8 @@ parseArgs(int argc, char **argv) { if (argv[i][0] != '-') { + /* Allow a call like "setxkbmap us" to work. Layout is default, + if -layout is given, then try parsing variant, then options */ if (!svSrc[LAYOUT_NDX]) trySetString(LAYOUT_NDX, argv[i], FROM_CMD_LINE); else if (!svSrc[VARIANT_NDX]) @@ -359,7 +393,7 @@ parseArgs(int argc, char **argv) else if (streq(argv[i], "-config")) ok = setOptString(&i, argc, argv, CONFIG_NDX, FROM_CMD_LINE); else if (streq(argv[i], "-device")) - deviceSpec = atoi(argv[++i]); + deviceSpec = atoi(argv[++i]); /* only allow device IDs, not names */ else if (streq(argv[i], "-display")) ok = setOptString(&i, argc, argv, DISPLAY_NDX, FROM_CMD_LINE); else if (streq(argv[i], "-geometry")) @@ -458,6 +492,11 @@ parseArgs(int argc, char **argv) return ok; } +/** + * Open a connection to the display and print error if it fails. + * + * @return True on success or False otherwise. + */ Bool getDisplay(int argc, char **argv) { @@ -507,6 +546,13 @@ getDisplay(int argc, char **argv) /***====================================================================***/ +/** + * Retrieve xkb values from th the XKB_RULES_NAMES property and store their + * contents in svValues. + * If the property cannot be read, the built-in defaults are used. + * + * @return True. + */ Bool getServerValues(void) { @@ -724,6 +770,12 @@ applyConfig(char *name) return True; } +/** + * If any of model, layout, variant or options is specified, then compile the + * options into the + * + * @return True on success or false otherwise. + */ Bool applyRules(void) { @@ -757,6 +809,8 @@ applyRules(void) } else { + /* try to load rules files from all include paths until the first + * we succeed with */ for (i = 0; (i < numInclPath) && (!rules); i++) { if ((strlen(inclPath[i]) + strlen(rfName) + 8) > PATH_MAX) @@ -774,6 +828,8 @@ applyRules(void) ERR1("Couldn't find rules file (%s) \n", svValue[RULES_NDX]); return False; } + /* Let the rules file to the magic, then update the svValues with + * those returned after processing the rules */ XkbRF_GetComponents(rules, &rdefs, &rnames); if (rnames.keycodes) { @@ -910,6 +966,7 @@ applyComponentNames(void) MSG("Trying to build keymap using the following components:\n"); dumpNames(False, True); } + /* Upload the new description to the server. */ if (dpy && !print) { XkbComponentNamesRec cmdNames; @@ -928,6 +985,7 @@ applyComponentNames(void) ERR("Error loading new keyboard description\n"); return False; } + /* update the XKB root property */ if (svValue[RULES_NDX] && (rdefs.model || rdefs.layout)) { if (!XkbRF_SetNamesProp(dpy, svValue[RULES_NDX], &rdefs)) -- cgit v1.2.3