Update Toggle Ducks Actions when Toggle Ducks Buttons changes.
[synfig.git] / synfig-osx / trunk / launcher / utils / dumpkeymap.man
1 .ig
2 //=============================================================================
3 //
4 // Manual page for `dumpkeymap'.
5 //
6 // Copyright (C) 1999,2000 by Eric Sunshine <sunshine@sunshineco.com>
7 // All rights reserved.
8 //
9 // Redistribution and use in source and binary forms, with or without
10 // modification, are permitted provided that the following conditions are met:
11 //
12 //   1. Redistributions of source code must retain the above copyright
13 //      notice, this list of conditions and the following disclaimer.
14 //   2. Redistributions in binary form must reproduce the above copyright
15 //      notice, this list of conditions and the following disclaimer in the
16 //      documentation and/or other materials provided with the distribution.
17 //   3. The name of the author may not be used to endorse or promote products
18 //      derived from this software without specific prior written permission.
19 //
20 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
21 // WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
22 // MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO
23 // EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
26 // OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
27 // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 // OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29 // ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 //
31 //=============================================================================
32 //
33 // $XFree86: xc/programs/Xserver/hw/darwin/utils/dumpkeymap.man,v 1.2 2000/12/05 21:18:34 dawes Exp $
34 //
35 ..
36 .ig
37 //-----------------------------------------------------------------------------
38 // Local identification information.
39 //-----------------------------------------------------------------------------
40 ..
41 .nr VE 4 \" Version number
42 .TH DUMPKEYMAP 1 "v\n(VE \-\- 1 December 2000" "Version \n(VE"
43 .de UP
44 1 December 2000
45 ..
46 .ig
47 //-----------------------------------------------------------------------------
48 // Annotation Macros
49 // -----------------
50 //      Facilitate creation of annotated, non-filled blocks of text.  An
51 //      annotated block is initiated with the `AS' macro.  Each annotated,
52 //      non-filled line within the block must be introduced with the `AN' macro
53 //      which takes three arguments.  The first argument is the detail text to
54 //      be annotated.  The second is a string of spaces used to align the
55 //      annotations by certain (broken) roff interpreters which fail to
56 //      implement the proper set of roff commands (such as diversions,
57 //      indentation, and tab stops).  It is assumed that the spaces will be
58 //      used with fixed-point font.  The third argument is the annotation
59 //      itself.  The block should be terminated with the `AE' macro.  For all
60 //      roff interpreters which properly implement diversions, indentation, and
61 //      tab stops, all anotations within the block are automatically aligned at
62 //      the same horizontal position.  This position is guaranteed to be just
63 //      to the right of the widest `AN' detail line.  For broken roff
64 //      interpreters, such as `rman', the string of spaces from the second
65 //      argument are used to align the annotations.  Finally, the `AZ' macro,
66 //      which takes a single argument, can be used to to insert a non-annotated
67 //      line into the block which does not play a part in the calculation of
68 //      the horizontal annotation alignment.
69 //
70 // Implementation Notes
71 // --------------------
72 // *1*  These macros utilize a diversion (named `AD').  Since the prevailing
73 //      indentation is stored along with the diverted text, we must muck with
74 //      the indentation level in order to prevent the indentation from being
75 //      applied to the text a second time when `AD' is finally emitted.
76 //
77 // *2*  Unfortunately, `.if' strips leading whitespace from following text, so
78 //      `AN' uses \& to preserve the whitespace.
79 //
80 // *3*  This manual page has been tested for proper formatting with troff,
81 //      groff, nroff and rman (the `man' to `HTML' converter).  Unfortunately,
82 //      rman fails to implement many useful features such as diversions,
83 //      indentation, and tab stops, and is also hideously buggy.  Furthermore
84 //      it identifies itself as nroff and fails to provide any further
85 //      identification, so there is no way to create macros which specifically
86 //      work around its limitations.  Following is a list of several bugs in
87 //      rman which the implementation of these macros must avoid:
88 //          o Fails with multi-line conditionals within macros.
89 //          o Fails on macro definition within multi-line conditionals.
90 //          o Fails when macro arguments are not delimited by exactly 1 space.
91 //          o String definition `.ds' ignores the value; uses empty "" instead.
92 //      As a consequence of these problems, the following macros are written
93 //      using a series of ugly single-line `.if' conditionals rather than the
94 //      more natural multi-line `.if' and `.ie' conditionals.  Also, rman fails
95 //      to understand the common idiom of `.\"' to introduce a comment, which
96 //      is why all comments in this file are wrapped in ignore `.ig' blocks.
97 //-----------------------------------------------------------------------------
98 ..
99 .de AS
100 .if t .nr AW 0
101 .if t .nr AI \\n(.i
102 .if t .in -\\n(AI
103 .nf
104 ..
105 .de AN
106 .if t .if \w'\\$1'>\\n(AW .nr AW \w'\\$1'
107 .if t .da AD
108 .if t \\&\\$1\\t\\$3
109 .if t .da
110 .if n \\&\\$1 \\$2\\$3
111 ..
112 .de AZ
113 .if t .da AD
114 \\$1
115 .if t .da
116 ..
117 .de AE
118 .if t .in +\\n(AIu
119 .if t .if \\n(AW .ta \\n(AWu+\w'\\(em'u
120 .if t .AD
121 .if t .DT
122 .if t .rm AD
123 .if t .rm AW
124 .fi
125 ..
126 .ig
127 //-----------------------------------------------------------------------------
128 // Bulleted list macros -- `BG' begins a bulleted list; `BU' delimits
129 //      bulleted entries; `BE' ends a bulleted list.
130 //-----------------------------------------------------------------------------
131 ..
132 .de BG
133 .PP
134 .RS
135 ..
136 .de BU
137 .HP
138 \\(bu\\ \\c
139 ..
140 .de BE
141 .RE
142 .PP
143 ..
144 .ig
145 //-----------------------------------------------------------------------------
146 // Indented paragraph with stylized hanging tag macro.  `TG' takes a single
147 //      argument and treats it as the hanging tag of the indented paragraph.
148 //      The tag is italicized in troff but not in nroff.
149 //-----------------------------------------------------------------------------
150 ..
151 .de TG
152 .TP
153 .ie t .I "\\$1"
154 .el \\$1
155 ..
156 .ig
157 //-----------------------------------------------------------------------------
158 // Manual page for `dumpkeymap'.
159 //-----------------------------------------------------------------------------
160 ..
161 .SH NAME
162 dumpkeymap \- Dianostic dump of a .keymapping file
163 .SH SYNOPSIS
164 .B dumpkeymap
165 .RI [ options "] [-] [" file "...]"
166 .SH DESCRIPTION
167 .I dumpkeymap
168 prints a textual representation of each Apple/\c
169 .SM NeXT
170 .I .keymapping
171 file mentioned on the command-line.  If no files are mentioned and if the
172 local machine is an Apple or
173 .SM NeXT
174 installation, then the key mapping currently in use by the WindowServer and the
175 AppKit is printed instead.
176 .SH OPTIONS
177 .TP
178 .B "\-h \-\^\-help"
179 Display general program instructions and option summary.
180 .TP
181 .B "\-k \-\^\-help\-keymapping"
182 Display a detailed description of the internal layout of a
183 .I .keymapping
184 file.  This is the same information as that presented in the
185 .I "Key Mapping Description"
186 section of this document.
187 .TP
188 .B "\-o \-\^\-help\-output"
189 Display an explanation of the output generated by
190 .I dumpkeymap
191 when dissecting a
192 .I .keymapping
193 file.  This is the same information as that presented in the
194 .I "Output Description"
195 section of this document.
196 .TP
197 .B "\-f \-\^\-help\-files"
198 Display a summary of the various files and directories which are related to
199 key mappings.  This is the same information as that presented in the
200 .I "Files"
201 section of this document.
202 .TP
203 .B "\-d \-\^\-help\-diagnostics"
204 Display a list of the various diagnostic messages which may be emitted by
205 .I dumpkeymap.
206 This is the same information as that presented in the
207 .I "Diagnostics"
208 section of this document.
209 .TP
210 .B "\-v \-\^\-version"
211 Display the
212 .I dumpkeymap
213 version number and warranty information.
214 .TP
215 .B "\- \-\^\-"
216 Inhibit processing of options at this point in the argument list.  An
217 occurrence of `\-' or `\-\^\-' in the argument list causes all following
218 arguments to be treated as file names even if an argument begins with a `\-'
219 character.
220 .SH "KEY MAPPING DESCRIPTION"
221 The following sections describe, in complete detail, the format of a raw key
222 mapping resource, as well as the format of the
223 .I .keymapping
224 file which encapsulates one or more raw mappings.
225 .SH "Types and Data"
226 The following type definitions are employed throughout this discussion:
227 .PP
228 .RS
229 .AS
230 .AZ "typedef unsigned char byte;"
231 .AZ "typedef unsigned short word;"
232 .AZ "typedef unsigned long dword;"
233 .AE
234 .RE
235 .PP
236 Additionally, the type definition
237 .RI ` number '
238 is used generically to
239 indicate a numeric value.  The actual size of the
240 .RI ` number '
241 type may be one or two bytes depending upon how the data is stored in the key
242 map.  Although most key maps use byte-sized numeric values, word-sized values
243 are also allowed.
244 .PP
245 Multi-byte values in a key mapping file are stored in big-endian byte order.
246 .SH "Key Mapping File and Device Mapping"
247 A key mapping file begins with a magic-number and continues with a
248 variable number of device-specific key mappings.
249 .PP
250 .RS
251 .AS
252 .AZ "struct KeyMappingFile {"
253 .AN "    char magic_number[4];" "   " "// `KYM1'"
254 .AN "    DeviceMapping maps[...];" "" "// Variable number of maps"
255 .AZ };
256 .AE
257 .PP
258 .AS
259 .AZ "struct DeviceMapping {"
260 .AN "    dword interface;" " " "// Interface type"
261 .AN "    dword handler_id;" "" "// Interface subtype"
262 .AN "    dword map_size;" "  " "// Byte count of `map' (below)"
263 .AN "    KeyMapping map;"
264 .AZ };
265 .AE
266 .RE
267 .PP
268 The value of `interface' represents a family of keyboard device types
269 (such as Intel
270 .SM "PC, ADB, NeXT,"
271 Sun Type5, etc.), and is generally specified as one of the constant values
272 .SM "NX_EVS_DEVICE_INTERFACE_ADB, NX_EVS_DEVICE_INTERFACE_ACE,"
273 etc., which are are defined in IOHIDTypes.h on MacOS/X and Darwin, and in
274 ev_types.h on MacOS/X Server, OpenStep, and NextStep.
275 .PP
276 The value of `handler_id' represents a specific keyboard layout within the
277 much broader `interface' family.  For instance, for a 101-key Intel
278 .SM PC
279 keyboard (of type
280 .SM NX_EVS_DEVICE_INTERFACE_ACE\c
281 ) the `handler_id' is '0', whereas for a 102-key keyboard it is `1'.
282 .PP
283 Together, `interface' and `handler_id' identify the exact keyboard hardware to
284 which this mapping applies.  Programs which display a visual representation of
285 a keyboard layout, match `interface' and `handler_id' from the
286 .I .keymapping
287 file against the `interface' and `handler_id' values found in each
288 .I .keyboard
289 file.
290 .SH "Key Mapping"
291 A key mapping completely defines the relationship of all scan codes with their
292 associated functionality.  A
293 .I KeyMapping
294 structure is embedded within the
295 .I DeviceMapping
296 structure in a
297 .IR KeyMappingFile .
298 The key mapping currently in use by the WindowServer and AppKit is also
299 represented by a
300 .I KeyMapping
301 structure, and can be referred to directly by calling NXGetKeyMapping() and
302 accessing the `mapping' data member of the returned
303 .I NXKeyMapping
304 structure.
305 .PP
306 .RS
307 .AS
308 .AZ "struct KeyMapping {"
309 .AN "    word number_size;" "          " "// 0=1 byte, non-zero=2 bytes"
310 .AN "    number num_modifier_groups;" "" "// Modifier groups"
311 .AZ "    ModifierGroup modifier_groups[...];"
312 .AN "    number num_scan_codes;" "     " "// Scan groups"
313 .AN "    ScanGroup scan_table[...];"
314 .AN "    number num_sequence_lists;" " " "// Sequence lists"
315 .AN "    Sequence sequence_lists[...];"
316 .AN "    number num_special_keys;" "   " "// Special keys"
317 .AN "    SpecialKey special_key[...];"
318 .AZ };
319 .AE
320 .RE
321 .PP
322 The `number_size' flag determines the size, in bytes, of all remaining numeric
323 values (denoted by the type definition
324 .RI ` number ')
325 within the
326 key mapping.  If its value is zero, then numbers are represented by a single
327 byte.  If it is non-zero, then numbers are represented by a word (two bytes).
328 .SH "Modifier Group"
329 A modifier group defines all scan codes which map to a particular type of
330 modifier, such as
331 .IR shift ,
332 .IR control ,
333 etc.
334 .PP
335 .RS
336 .AS
337 .AZ "enum Modifier {"
338 .AZ "    ALPHALOCK = 0,"
339 .AZ "    SHIFT,"
340 .AZ "    CONTROL,"
341 .AZ "    ALTERNATE,"
342 .AZ "    COMMAND,"
343 .AZ "    KEYPAD,"
344 .AZ "    HELP"
345 .AZ };
346 .AE
347 .PP
348 .AS
349 .AZ "struct ModifierGroup {"
350 .AN "    number modifier;" "       " "// A Modifier constant"
351 .AN "    number num_scan_codes;"
352 .AN "    number scan_codes[...];" "" "// Variable number of scan codes"
353 .AZ };
354 .AE
355 .RE
356 .PP
357 The scan_codes[] array contains a list of all scan codes which map to the
358 specified modifier.  The
359 .IR shift ", " command ", and " alternate
360 modifiers are frequently mapped to two different scan codes, apiece,
361 since these modifiers often appear on both the left and right sides of
362 the keyboard.
363 .SH "Scan Group"
364 There is one
365 .I ScanGroup
366 for each scan code generated by the given keyboard.  This number is given by
367 KeyMapping::num_scan_codes.  The first scan group represents hardware scan
368 code 0, the second represents scan code 1, etc.
369 .PP
370 .RS
371 .AS
372 .AZ "enum ModifierMask {"
373 .AN "    ALPHALOCK_MASK" "      " "= 1 << 0,"
374 .AN "    SHIFT_MASK" "          " "= 1 << 1,"
375 .AN "    CONTROL_MASK" "        " "= 1 << 2,"
376 .AN "    ALTERNATE_MASK" "      " "= 1 << 3,"
377 .AN "    CARRIAGE_RETURN_MASK" "" "= 1 << 4"
378 .AZ };
379 .AZ "#define NOT_BOUND 0xff"
380 .AE
381 .PP
382 .AS
383 .AZ "struct ScanGroup {"
384 .AN "    number mask;"
385 .AN "    Character characters[...];"
386 .AZ };
387 .AE
388 .RE
389 .PP
390 For each scan code, `mask' defines which modifier combinations generate
391 characters.  If `mask' is
392 .SM NOT_BOUND
393 (0xff) then then this scan code does not generate any characters ever, and its
394 characters[] array is zero length.  Otherwise, the characters[] array contains
395 one
396 .I Character
397 record for each modifier combination.
398 .PP
399 The number of records in characters[] is determined by computing (1 <<
400 bits_set_in_mask).  In other words, if mask is zero, then zero bits are set,
401 so characters[] contains only one record.  If `mask' is
402 .SM "(SHIFT_MASK | CONTROL_MASK),"
403 then two bits are set, so characters[] contains four records.
404 .PP
405 The first record always represents the character which is generated by that
406 key when no modifiers are active.  The remaining records represent characters
407 generated by the various modifier combinations.  Using the example with the
408 .I shift
409 and
410 .I control
411 masks set, record two would represent the character with the
412 .I shift
413 modifier active; record three, the
414 .I control
415 modifier active; and record four, both the
416 .I shift
417 and
418 .I control
419 modifiers active.
420 .PP
421 As a special case,
422 .SM ALPHALOCK_MASK
423 implies
424 .SM SHIFT_MASK,
425 though only
426 .SM ALPHALOCK_MASK
427 appears in `mask'.  In this case the same character is generated for both the
428 .I shift
429 and
430 .I alpha-lock
431 modifiers, but only needs to appear once in the characters[] array.
432 .PP
433 .SM CARRIAGE_RETURN_MASK
434 does not actually refer to a modifier key.  Instead, it is used to
435 distinguish the scan code which is given the special pseudo-designation of
436 .I "carriage return"
437 key.  Typically, this mask appears solo in a
438 .I ScanGroup
439 record and only the two
440 .I Character
441 records for control-M and control-C follow.  This flag may be a throwback to
442 an earlier time or may be specially interpreted by the low-level keyboard
443 driver, but its purpose is otherwise enigmatic.
444 .SH Character
445 Each
446 .I Character
447 record indicates the character generated when this key is pressed, as well as
448 the character set which contains the character.  Well known character sets are
449 .SM `ASCII'
450 and `Symbol'.  The character set can also be one of the meta values
451 .SM FUNCTION_KEY
452 or
453 .SM KEY_SEQUENCE.
454 If it is
455 .SM FUNCTION_KEY
456 then `char_code' represents a generally well-known function key such as those
457 enumerated by
458 .I FunctionKey.
459 If the character set is
460 .SM KEY_SEQUENCE
461 then `char_code' represents is a zero-base index into
462 KeyMapping::sequence_lists[].
463 .PP
464 .RS
465 .AS
466 .AZ "enum CharacterSet {"
467 .AN "    ASCII" "       " "= 0x00,"
468 .AN "    SYMBOL" "      " "= 0x01,"
469 .AN "    ..."
470 .AN "    FUNCTION_KEY" "" "= 0xfe,"
471 .AN "    KEY_SEQUENCE" "" "= 0xff"
472 .AZ };
473 .AE
474 .PP
475 .AS
476 .AZ "struct Character {"
477 .AN "    number set;" "      " "// CharacterSet of generated character"
478 .AN "    number char_code;" "" "// Actual character generated"
479 .AZ };
480 .AE
481 .PP
482 .AS
483 .AZ "enum FunctionKey {"
484 .AZ "    F1 = 0x20, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,"
485 .AZ "    INSERT, DELETE, HOME, END, PAGE_UP, PAGE_DOWN, PRINT_SCREEN,"
486 .AZ "    SCROLL_LOCK, PAUSE, SYS_REQUEST, BREAK, RESET, STOP, MENU,"
487 .AZ "    USER, SYSTEM, PRINT, CLEAR_LINE, CLEAR_DISPLAY, INSERT_LINE,"
488 .AZ "    DELETE_LINE, INSERT_CHAR, DELETE_CHAR, PREV, NEXT, SELECT"
489 .AZ };
490 .AE
491 .RE
492 .SH Sequence
493 When Character::set contains the meta value
494 .SM KEY_SEQUENCE,
495 the scan code is bound to a sequence of keys rather than a single character.
496 A sequence is a series of modifiers and characters which are automatically
497 generated when the associated key is depressed.
498 .PP
499 .RS
500 .AS
501 .AZ "#define MODIFIER_KEY 0xff"
502 .AE
503 .PP
504 .AS
505 .AZ "struct Sequence {"
506 .AN "    number num_chars;"
507 .AN "    Character characters[...];"
508 .AZ };
509 .AE
510 .RE
511 .PP
512 Each generated
513 .I Character
514 is represented as previously described, with the exception that
515 .SM MODIFIER_KEY
516 may appear in place of
517 .SM KEY_SEQUENCE.
518 When the value of Character::set is
519 .SM MODIFIER_KEY
520 then Character::char_code represents a modifier key rather than an actual
521 character.  If the modifier represented by `char_code' is non-zero, then it
522 indicates that the associated modifier key has been depressed.  In this case,
523 the value is one of the constants enumerated by
524 .I Modifier
525 (\c
526 .SM "SHIFT, CONTROL, ALTERNATE,"
527 etc.).  If the value is zero then it means that the modifier keys have been
528 released.
529 .SH "Special Key"
530 A special key is one which is scanned directly by the Mach kernel rather than
531 by the WindowServer.  In general, events are not generated for special keys.
532 .PP
533 .RS
534 .AS
535 .AZ "enum SpecialKeyType {"
536 .AZ "    VOLUME_UP = 0,"
537 .AZ "    VOLUME_DOWN,"
538 .AZ "    BRIGHTNESS_UP,"
539 .AZ "    BRIGHTNESS_DOWN,"
540 .AZ "    ALPHA_LOCK,"
541 .AZ "    HELP,"
542 .AZ "    POWER,"
543 .AZ "    SECONDARY_ARROW_UP,"
544 .AZ "    SECONDARY_ARROW_DOWN"
545 .AZ };
546 .AE
547 .PP
548 .AS
549 .AZ "struct SpecialKey {"
550 .AN "    number type;" "     " "// A SpecialKeyType constant"
551 .AN "    number scan_code;" "" "// Actual scan code"
552 .AZ };
553 .AE
554 .RE
555 .SH OUTPUT
556 What follows is an explanation and description of the various pieces of
557 information emitted by
558 .I dumpkeymap.
559 .PP
560 For a more thorough discussion of any particular piece of information described
561 here, refer to the detailed description of the internal layout of a key mapping
562 provided by the
563 .I "Key Mapping Description"
564 section above.
565 .SH Conventions
566 Depending upon context, some numeric values are displayed in decimal
567 notation, whereas others are displayed in hexadecimal notation.
568 Hexadecimal numbers are denoted by a `0x' prefix (for instance, `0x7b'),
569 except when explicitly noted otherwise.
570 .SH "Key Mapping Source"
571 The first piece of information presented about a particular key mapping is the
572 source from which the data was gleaned.  For a
573 .I .keymapping
574 file, the title
575 .SM "`KEYMAP FILE'"
576 is emitted along with the path and name of the file in question.  For the key
577 mapping currently in use by the WindowServer and AppKit, the title
578 .SM "`ACTIVE KEYMAP'"
579 is emitted instead.
580 .SH "Device Information"
581 Each
582 .I .keymapping
583 file may contain one or more raw key mappings.  For example, a file which maps
584 keys to a Dvorak-style layout might contain raw mappings for Intel
585 .SM "PC, ADB, NeXT,"
586 and Sun Type5 keyboards.
587 .PP
588 For each raw mapping, the following information is emitted:
589 .BG
590 .BU
591 The title
592 .SM `KEYMAP'
593 along with the mapping's relative position in the
594 .I .keymapping
595 file.
596 .BU
597 The `interface' identifier.
598 .BU
599 The `handler_id' sub-identifier.
600 .BU
601 The size of the raw mapping resource counted in bytes.
602 .BE
603 The `interface' and `handler_id' values, taken together, define a specific
604 keyboard device.  A
605 .I .keyboard
606 file, which describes the visual layout of a keyboard, also contains
607 `interface' and `handler_id' identifiers.  The
608 .I .keyboard
609 file corresponding to a particular key mapping can be found by matching the
610 `interface' and `handler_id' values from each resource.
611 .SH Modifiers
612 Each mapping may contain zero or more modifier records which associate hardware
613 scan codes with modifier descriptions such as
614 .I "shift, control, alternate,"
615 etc.  The title
616 .SM `MODIFIERS'
617 is printed along with the count of modifier records which follow.  For each
618 modifier record, the modifier's name is printed along with a list of scan
619 codes, in hexadecimal format, which generate that modifier value.  For example:
620 .PP
621 .RS
622 .nf
623 MODIFIERS [4]
624 alternate: 0x1d 0x60
625 control: 0x3a
626 keypad: 0x52 0x53 ... 0x63 0x62
627 shift: 0x2a 0x36
628 .fi
629 .RE
630 .SH Characters
631 Each mapping may contain zero or more character records which associate
632 hardware scan codes with the actual characters generated by those scan
633 codes in the presence or absence of various modifier combinations.  The
634 title
635 .SM `CHARACTERS'
636 is printed along with the count of character records which follow.  Here is a
637 highly abbreviated example:
638 .PP
639 .RS
640 .nf
641 CHARACTERS [9]
642 scan 0x00: -AC-L  "a" "A" "^A" "^A" ca c7 "^A" "^A"
643 scan 0x07: -AC-L  "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
644 scan 0x0a: ---S-  "<" ">"
645 scan 0x13: -ACS-  "2" "@" "^@" "^@" b2 b3 "^@" "^@"
646 scan 0x24: R----  "^M" "^C"
647 scan 0x3e: -----  [F4]
648 scan 0x4a: -----  [page up]
649 scan 0x60: -----  {seq#3}
650 scan 0x68: not-bound
651 .fi
652 .RE
653 .PP
654 For each record, the hexadecimal value of the hardware scan code is printed,
655 followed by a list of modifier flag combinations and the actual characters
656 generated by this scan code with and without modifiers applied.
657 .PP
658 The modifier flags field is composed of a combination of single letter
659 representations of the various modifier types.  The letters stand for:
660 .PP
661 .RS
662 .nf
663 L \- alpha-lock
664 S \- shift
665 C \- control
666 A \- alternate
667 R \- carriage-return
668 .fi
669 .RE
670 .PP
671 As a special case, the
672 .I alpha-lock
673 flag also implies the
674 .I shift
675 flag, so these two flags never appear together in the same record.
676 .PP
677 The combination of modifier flags determines the meaning and number of fields
678 which follow.  The first field after the modifier flags always represents the
679 character that will be generated if no modifier keys are depressed.  The
680 remaining fields represent characters generated by the various modifier
681 combinations.  The order of the fields follows this general pattern:
682 .BG
683 .BU
684 The character generated by this scan code when no modifiers are in effect is
685 listed first.
686 .BU
687 If the `L' or `S' flag is active, then the shifted character generated by this
688 scan code is listed next.
689 .BU
690 If the `C' flag is active, then the control-character generated by this scan
691 code is listed next.  Furthermore, if the `L' or `S' flag is also active, then
692 the shifted control-character is listed after that.
693 .BU
694 If the `A' flag is active, then the alternate-character generated by this scan
695 code is listed next.  Furthermore, if the `L' or `S' flag is active, then the
696 shifted alternate-character is listed after that.  If the `C' flag is also
697 active, then the alternate-control-character is listed next.  Finally, if the
698 `C' and `L' or `C' and `S' flags are also active, then the shifted
699 alternate-control-character is listed.
700 .BE
701 The `R' flag does not actually refer to a modifier key.  Instead, it is used to
702 distinguish the scan code which is given the special pseudo-designation of
703 .I "carriage return"
704 key.  Typically, this mask appears solo and only the two fields for control-M
705 and control-C follow.  This flag may be a throwback to an earlier time or may
706 be specially interpreted by the low-level keyboard driver, but its purpose is
707 otherwise enigmatic.
708 .PP
709 Recalling the example from above, the following fields can be identified:
710 .PP
711 .RS
712 .nf
713 scan 0x00: -AC-L  "a" "A" "^A" "^A" ca c7 "^A" "^A"
714 .fi
715 .RE
716 .BG
717 .BU
718 Lower-case `a' is generated when no modifiers are active.
719 .BU
720 Upper-case `A' is generated when
721 .IR shift " or " alpha-lock
722 are active.
723 .BU
724 Control-A is generated when
725 .I control
726 is active.
727 .BU
728 Control-A is generated when
729 .IR control " and " shift
730 are active.
731 .BU
732 The character represented by the hexadecimal code 0xca is generated when
733 .I alternate
734 is active.
735 .BU
736 The character represented by 0xc7 is generated when
737 .IR alternate " and " shift " (or " alpha-lock ") are active."
738 .BU
739 Control-A is generated when
740 .IR alternate " and " control
741 are active.
742 .BU
743 Control-A is generated when
744 .IR "alternate, control" " and " shift " (or " alpha-lock ") are active."
745 .BE
746 The notation used to represent a particular generated character varies.
747 .BG
748 .BU
749 Printable
750 .SM ASCII
751 characters are quoted, as in "x" or "X".
752 .BU
753 Control-characters are quoted and prefixed with `^', as in "^X".
754 .BU
755 Characters with values greater than 127 (0x7f) are displayed as hexadecimal
756 values without the `0x' prefix.
757 .BU
758 Characters in a non-\c
759 .SM ASCII
760 character set (such as `Symbol') are displayed as two hexadecimal numbers
761 separated by a slash, as in `01/4a'.  The first number is the character set's
762 identification code (such as `01' for the `Symbol' set), and the second number
763 is the value of the generated character.
764 .BU
765 Non-printing special function characters are displayed with the function's
766 common name enclosed in brackets, as in `[page up]' or `[F4]'.
767 .BU
768 If the binding represents a key sequence rather than a single character, then
769 the sequence's identification number is enclosed in braces, as in `{seq#3}'.
770 .BE
771 Recalling a few examples from above, the following interpretations can be made:
772 .PP
773 .RS
774 .nf
775 scan 0x07: -AC-L  "x" "X" "^X" "^X" 01/b4 01/ce "^X" "^X"
776 scan 0x3e: -----  [F4]
777 scan 0x4a: -----  [page up]
778 scan 0x60: -----  {seq#3}
779 .fi
780 .RE
781 .BG
782 .BU
783 "x" and "X" are printable
784 .SM ASCII
785 characters.
786 .BU
787 "^X" is a control-character.
788 .BU
789 `01/b4' and `01/ce' represent the character codes 0xb4 and 0xce in the `Symbol'
790 character set.
791 .BU
792 Scan code 0x3e generates function-key `F4', and scan code 0x4a generates
793 function-key `page up'.
794 .BU
795 Scan code 0x60 is bound to key sequence #3.
796 .BE
797 Finally, if a scan code is not bound to any characters, then it is annotated
798 with the label `not-bound', as with example scan code 0x68 from above.
799 .SH Sequences
800 A scan code (modified and unmodified) can be bound to a key sequence rather
801 than generating a single character or acting as a modifier.  When it is bound
802 to a key sequence, a series of character invocations and modifier actions are
803 automatically generated rather than a single keystroke.
804 .PP
805 Each mapping may contain zero or more key sequence records.  The title
806 .SM `SEQUENCES'
807 is printed along with the count of sequence records which follow.  For example:
808 .PP
809 .RS
810 .nf
811 SEQUENCES [3]
812 sequence 0: "f" "o" "o"
813 sequence 1: {alternate} "b" "a" "r" {unmodify}
814 sequence 2: [home] "b" "a" "z"
815 .fi
816 .RE
817 .PP
818 The notation used to represent the sequence of generated characters is
819 identical to the notation already described in the
820 .I Characters
821 section above, with the exception that modifier actions may be interposed
822 between generated characters.  Such modifier actions are represented by the
823 modifier's name enclosed in braces.  The special name `{unmodify}' indicates
824 the release of the modifier keys.
825 .PP
826 Thus, the sequences in the above example can be interpreted as follows:
827 .BG
828 .BU
829 Sequence\ #0 generates `foo'.
830 .BU
831 Sequence\ #1 invokes the
832 .I alternate
833 modifier, generates `bar', and then releases
834 .I alternate.
835 .BU
836 Sequence\ #2 invokes the
837 .I home
838 key and then generates `baz'.  In a text editor, this would probably result in
839 `baz' being prepended to the line of text on which the cursor resides.
840 .BE
841 .SH Special Keys
842 Certain keyboards feature keys which perform some type of special purpose
843 function rather than generating a character or acting as a modifier.  For
844 instance, Apple keyboards often contain a
845 .I power
846 key, and
847 .SM NeXT
848 keyboards have historically featured screen brightness and volume control keys.
849 .PP
850 Each mapping may contain zero or more special-key records which associate
851 hardware scan codes with such special purpose functions.  The title
852 .SM `SPECIALS'
853 is printed along with the count of records which follow.  For each record, the
854 special function's name is printed along with a list of scan codes, in
855 hexadecimal format, which are bound to that function.  For example:
856 .PP
857 .RS
858 .nf
859 SPECIALS [6]
860 alpha-lock: 0x39
861 brightness-down: 0x79
862 brightness-up: 0x74
863 power: 0x7f
864 sound-down: 0x77
865 sound-up: 0x73
866 .fi
867 .RE
868 .SH FILES
869 .IP *.keymapping
870 A key mapping file which precisely defines the relationship of all
871 hardware-specific keyboard scan-codes with their associated functionality.
872 .IP *.keyboard
873 A file describing the physical layout of keys on a particular type of
874 keyboard.  Each `key' token in this file defines the position and shape of the
875 key on the keyboard, as well as the associated scan code which that key
876 generates.  A
877 .I .keymapping
878 file, on the other hand, defines the characters which are generated by a
879 particular scan code depending upon the state of the various modifier keys
880 (such as
881 .I shift,
882 .I control,
883 etc.).  The `interface' and `handler_id' values from a
884 .I .keymapping
885 file are matched against those in each
886 .I .keyboard
887 file in order to associate a particular
888 .I .keyboard
889 file with a key mapping.  Various
890 .SM GUI
891 programs use the
892 .I .keyboard
893 file to display a visual representation of a keyboard for the user.  Since
894 these files are just plain text, they can be easily viewed and interpreted
895 without the aid of a specialized program, thus
896 .I dumpkeymap
897 leaves these files alone.
898 .PP
899 /System/Library/Keyboards
900 .br
901 /Network/Library/Keyboards
902 .br
903 /Local/Library/Keyboards
904 .br
905 /Library/Keyboards
906 .RS
907 Repositories for
908 .I .keymapping
909 and
910 .I .keyboard
911 files for MacOS/X, Darwin, and MacOS/X Server.
912 .RE
913 .PP
914 /NextLibrary/Keyboards
915 .br
916 /LocalLibrary/Keyboards
917 .RS
918 Repositories for
919 .I .keymapping
920 and
921 .I .keyboard
922 files for OpenStep and NextStep.
923 .RE
924 .IP $(HOME)/Library/Keyboards
925 Repository for personal
926 .I .keymapping
927 and
928 .I .keyboard
929 files.
930 .SH DIGANOSTICS
931 The following diagnostic messages may be issued to the standard error stream.
932 .TG "Unrecognized option."
933 An unrecognized option was specified on the command-line.  Invoke
934 .I dumpkeymap
935 with the
936 .B "\-\^\-help"
937 option to view a list of valid options.
938 .TG "Insufficient data in keymapping data stream."
939 The key mapping file or data stream is corrupt.  Either the file has been
940 incorrectly truncated or a field, such as those which indicates the number of
941 variable records which follow, contains a corrupt value.
942 .PP
943 The following diagnostic messages have significance only when trying to print
944 .I .keymapping
945 files mentioned on the command-line.
946 .TG "Bad magic number."
947 The mentioned file is not a
948 .I .keymapping
949 file.  The file's content does not start with the string `KYM1'.
950 .TG "Unable to open key mapping file."
951 The call to fopen() failed; probably because the specified path is invalid or
952 .I dumpkeymap
953 does not have permission to read the file.
954 .TG "Unable to determine key mapping file size."
955 The call to fstat() failed, thus memory can not be allocated for loading the
956 file.
957 .TG "Unable to read key mapping file."
958 The call to fread() failed.
959 .PP
960 The following diagnostic messages have significance only when trying to print
961 the currently active key mapping when no
962 .I .keymapping
963 files have been mentioned on the command-line.
964 .TG "Unable to open event status driver."
965 The call to NXOpenEventStatus() failed.
966 .TG "Bad key mapping length."
967 The call to NXKeyMappingLength() returned a bogus value.
968 .TG "Unable to get current key mapping."
969 The call to NXGetKeyMapping() failed.
970 .PP
971 The following diagnostic messages have significance only when using
972 .I dumpkeymap
973 on a non-Apple/\c
974 .SM NeXT
975 platform.
976 .TG "Must specify at least one .keymapping file."
977 No
978 .I .keymapping
979 files were mentioned on the command-line.  On non-Apple/\c
980 .SM NeXT
981 platforms, there is no concept of a currently active
982 .I .keymapping
983 file, so at least one file must be mentioned on the command-line.
984 .SH AUTHOR
985 Eric Sunshine <sunshine@sunshineco.com> wrote
986 .I dumpkeymap
987 and this document, the
988 .I "dumpkeymap user's manual."
989 Both
990 .I dumpkeymap
991 and this document are copyright \(co1999,2000 by Eric Sunshine
992 <sunshine@sunshineco.com>.  All rights reserved.
993 .PP
994 The implementation of
995 .I dumpkeymap
996 is based upon information gathered on September 3, 1997 by Eric Sunshine
997 <sunshine@sunshineco.com> and Paul S. McCarthy <zarnuk@zarnuk.com> during an
998 effort to reverse engineer the format of the
999 .SM NeXT
1000 .I .keymapping
1001 file.
1002 .if n .PP
1003 .if n Version \n(VE \-\-
1004 .if n .UP