diff --git a/docs/AUTHORS.txt b/docs/AUTHORS.txt index 996b1a706..24740d864 100644 --- a/docs/AUTHORS.txt +++ b/docs/AUTHORS.txt @@ -7,7 +7,7 @@ Various contributors (see below, and CHANGES.txt) http://www.tuxpaint.org/ -June 17, 2002 - July 30, 2020 +June 17, 2002 - August 29, 2020 $Id$ @@ -111,7 +111,7 @@ $Id$ Ankit Choudary , as part of GSOC 2010, with integration and fixes by Pere Pujal i Carabantes - Onscreen keyboard support + On-screen keyboard support Some code from Ankit Choudary , as part of GSOC 2010, diff --git a/docs/en/EXTENDING.txt b/docs/en/EXTENDING.txt index 3ee1d19fb..362c7b315 100644 --- a/docs/en/EXTENDING.txt +++ b/docs/en/EXTENDING.txt @@ -748,8 +748,127 @@ On-screen Keyboard As of version 0.9.22, Tux Paint's "Text" and "Label" tools can present an on-screen keyboard that allows the pointer (via a mouse, eye-tracking - systems, etc.) to be used to input characters. + systems, etc.) to be used to input characters. Files that describe the + layout and available keys are stored in Tux Paint's "osk" directory. + Each keyboard layout is defined by a number of files (some of which may + be shared by different layouts). We'll use the QWERTY keyboard as an + example: - Details forthcoming + qwerty.layout + + This is a text file that specifies the other files used to describe + the layout and key mappings. + + layout qwerty.h_layout + keymap us-intl-altgr-dead-keys.keymap + dead_keys_map dead_keys.map + composemap en_US.UTF-8_Compose + keysymdefs keysymdef.h + keyboardlist qwerty.layout default.layout + + Note: Blank lines within the ".layout" file will be ignored, as will + any text following a "#" (pound/hash) character — it can be used to + denote comments, as seen in the example above. + + qwerty.h_layout + + This describes how big the keyboard is (as a W×H grid), and lists each + key with its numeric keycode (see the "keymap" file, below), the width + it should be drawn at (typically "1.0", to take one space on the + keyboard, but in the example below, notice the "TAB" and "SPACE" keys + are much wider), the character or text to display on the key, + depending on which modifier keys have been pressed (one each for: no + modifiers, [Shift], [AltGr], and [Shift]+[AltGr]), and finally whether + or not the key is affected by the [CapsLock] key (use "1") or [AltGr] + (alternate graphics) key (use "2"), or not at all (use "0"). + + WIDTH 15 + HEIGHT 5 + + KEY 49 1.0 ` ~ ` ~ 0 + KEY 10 1.0 1 ! ¡ ¹ 0 + KEY 11 1.0 2 @ ² ˝ 0 + KEY 12 1.0 3 # · ³ 0 + KEY 13 1.0 4 $ ¤ £ 0 + KEY 14 1.0 5 % € ¸ 0 + KEY 15 1.0 6 ^ ¼ ^ 0 + ... + KEY 21 1.0 = + × ÷ 0 + KEY 22 2.0 DELETE DELETE DELETE DELETE 0 + + NEWLINE + + KEY 23 1.5 TAB TAB TAB TAB 0 + KEY 24 1.0 q Q ä Ä 1 + KEY 25 1.0 w W å Å 1 + KEY 26 1.0 e E é É 1 + KEY 27 1.0 r R ® ® 1 + ... + + NEWLINE + + # Arrow to left will change to the previous keyboard + KEY 2 1.0 <- <- <- <- 0 + + KEY 133 2.0 Cmp Cmp Cmp Cmp 0 + + # The ALT or ALTGR keys are used in im to switch the input mode. + KEY 64 2.0 Alt Alt Alt Alt 0 + + # Space + KEY 65 7.0 SPACE SPACE SPACE SPACE 0 + + KEY 108 2.0 AltGr AltGr AltGr AltGr 0 + + # Arrow to right will change to the next keyboard + KEY 1 1.0 -> -> -> -> 0 + + Notice here that alphabetic keys ([Q], [W], etc.) will be affected by + [CapsLock], while numeric keys ([1], [2], etc.), [Space], and so on, + will not. + + us-intl-altgr-dead-keys.keymap + + This file defines which numeric keycodes (seen in the keyboard layout + files, such as "qwerty.h_layout" described above) should be mapped to + which actual characters that an application such as Tux Paint expects + to receive when keys (e.g., on a real keyboard) are pressed. + + If you're using an operating system such as Linux, which runs X-Window + and has the "xmodmap" command-line tool available, you can run it with + the ("print keymap expressions" option, "-pke", to generate a keymap + file. + + keycode 9 = Escape NoSymbol Escape Escape + keycode 10 = 1 exclam exclamdown onesuperior 1 exclam 1 exclam + NoSymbol onesuperior + keycode 11 = 2 at twosuperior dead_doubleacute 2 at 2 at onehalf + twosuperior + keycode 12 = 3 numbersign periodcentered threesuperior dead_macron + periodcentered + ... + keycode 52 = z Z ae AE Arabic_hamzaonyeh asciitilde guillemotright + NoSymbol Greek_zeta Greek_ZETA U037D U03FF + keycode 53 = x X x X Arabic_hamza Arabic_sukun guillemotleft + NoSymbol Greek_chi Greek_CHI rightarrow leftarrow + keycode 54 = c C copyright cent Arabic_hamzaonwaw braceright + Greek_psi Greek_PSI copyright + keycode 55 = v V v V Arabic_ra braceleft Greek_omega Greek_OMEGA + U03D6 + keycode 56 = b B b B UFEFB UFEF5 Greek_beta Greek_BETA U03D0 + keycode 57 = n N ntilde Ntilde Arabic_alefmaksura Arabic_maddaonalef + Greek_nu Greek_NU U0374 U0375 + keycode 58 = m M mu mu Arabic_tehmarbuta apostrophe Greek_mu + Greek_MU U03FB U03FA + keycode 59 = comma less ccedilla Ccedilla Arabic_waw comma comma + less guillemotleft + keycode 60 = period greater dead_abovedot dead_caron Arabic_zain + period period greater guillemotright periodcentered + keycode 61 = slash question questiondown dead_hook Arabic_zah + Arabic_question_mark slash question + keycode 62 = Shift_R NoSymbol Shift_R Shift_R + ... + + ...Work in progress... ---------------------------------------------------------------------- diff --git a/docs/en/html/EXTENDING.html b/docs/en/html/EXTENDING.html index c4bd0fd6b..838ece94d 100644 --- a/docs/en/html/EXTENDING.html +++ b/docs/en/html/EXTENDING.html @@ -1586,11 +1586,158 @@ As of version 0.9.22, Tux Paint's "Text" and "Label" tools can present an on-screen keyboard that allows the pointer (via a mouse, eye-tracking systems, etc.) to be used to - input characters. + input characters. Files that describe the layout and available keys + are stored in + Tux Paint's + "osk" directory. Each keyboard layout is defined by a number + of files (some of which may be shared by different layouts). We'll use + the QWERTY keyboard as an example:

+ +

qwerty.layout

+
+

+ This is a text file that specifies the other files used to describe the + layout and key mappings. +

+
+

+ + layout qwerty.h_layout
+ keymap us-intl-altgr-dead-keys.keymap
+ dead_keys_map dead_keys.map
+ composemap en_US.UTF-8_Compose
+ keysymdefs keysymdef.h
+ keyboardlist qwerty.layout default.layout + +

+
+

+ Note: Blank lines within the ".layout" file + will be ignored, as will any text following a + "#" (pound/hash) character — it can be used to + denote comments, as seen in the example above. +

+
+ +

qwerty.h_layout

+
+

+ This describes how big the keyboard is (as a W×H grid), + and lists each key with its numeric keycode (see the "keymap" + file, below), the width it should be drawn at (typically + "1.0", to take one space on the keyboard, + but in the example below, notice the "TAB" and + "SPACE" keys are much wider), the character or + text to display on the key, depending on which modifier + keys have been pressed (one each for: no modifiers, + [Shift], [AltGr], and [Shift]+[AltGr]), + and finally whether or not the key is affected by the + [CapsLock] key (use "1") or + [AltGr] (alternate graphics) key (use "2"), + or not at all (use "0"). +

+
+

+ + WIDTH 15
+ HEIGHT 5
+
+ KEY 49 1.0 ` ~ ` ~ 0
+ KEY 10 1.0 1 ! ¡ ¹ 0
+ KEY 11 1.0 2 @ ² ˝ 0
+ KEY 12 1.0 3 # · ³ 0
+ KEY 13 1.0 4 $ ¤ £ 0
+ KEY 14 1.0 5 % € ¸ 0
+ KEY 15 1.0 6 ^ ¼ ^ 0
+ ...
+ KEY 21 1.0 = + × ÷ 0
+ KEY 22 2.0 DELETE DELETE DELETE DELETE 0
+
+ NEWLINE
+
+ KEY 23 1.5 TAB TAB TAB TAB 0
+ KEY 24 1.0 q Q ä Ä 1
+ KEY 25 1.0 w W å Å 1
+ KEY 26 1.0 e E é É 1
+ KEY 27 1.0 r R ® ® 1
+ ...
+
+ NEWLINE
+
+ # Arrow to left will change to the previous keyboard
+ KEY 2 1.0 <- <- <- <- 0
+
+ KEY 133 2.0 Cmp Cmp Cmp Cmp 0
+
+ # The ALT or ALTGR keys are used in im to switch the input mode.
+ KEY 64 2.0 Alt Alt Alt Alt 0
+
+ # Space
+ KEY 65 7.0 SPACE SPACE SPACE SPACE 0
+
+ KEY 108 2.0 AltGr AltGr AltGr AltGr 0
+
+ # Arrow to right will change to the next keyboard
+ KEY 1 1.0 -> -> -> -> 0 + +

+
+

+ Notice here that alphabetic keys ([Q], [W], etc.) + will be affected by [CapsLock], while numeric keys + ([1], [2], etc.), [Space], and so on, + will not. +

+
+ +

us-intl-altgr-dead-keys.keymap

+
+

+ This file defines which numeric keycodes (seen in the + keyboard layout files, such as "qwerty.h_layout" + described above) should be mapped to which actual characters + that an application such as + Tux Paint + expects to receive when keys (e.g., on a real keyboard) + are pressed. +

+

+ If you're using an operating system such as Linux, + which runs X-Window and has the + "xmodmap" command-line tool available, you can run + it with the ("print keymap expressions" + option, "-pke", to generate a keymap file. +

+
+

+ + keycode 9 = Escape NoSymbol Escape Escape
+ keycode 10 = 1 exclam exclamdown onesuperior 1 exclam 1 exclam NoSymbol onesuperior
+ keycode 11 = 2 at twosuperior dead_doubleacute 2 at 2 at onehalf twosuperior
+ keycode 12 = 3 numbersign periodcentered threesuperior dead_macron periodcentered
+ ...
+ keycode 52 = z Z ae AE Arabic_hamzaonyeh asciitilde guillemotright NoSymbol Greek_zeta Greek_ZETA U037D U03FF
+ keycode 53 = x X x X Arabic_hamza Arabic_sukun guillemotleft NoSymbol Greek_chi Greek_CHI rightarrow leftarrow
+ keycode 54 = c C copyright cent Arabic_hamzaonwaw braceright Greek_psi Greek_PSI copyright
+ keycode 55 = v V v V Arabic_ra braceleft Greek_omega Greek_OMEGA U03D6
+ keycode 56 = b B b B UFEFB UFEF5 Greek_beta Greek_BETA U03D0
+ keycode 57 = n N ntilde Ntilde Arabic_alefmaksura Arabic_maddaonalef Greek_nu Greek_NU U0374 U0375
+ keycode 58 = m M mu mu Arabic_tehmarbuta apostrophe Greek_mu Greek_MU U03FB U03FA
+ keycode 59 = comma less ccedilla Ccedilla Arabic_waw comma comma less guillemotleft
+ keycode 60 = period greater dead_abovedot dead_caron Arabic_zain period period greater guillemotright periodcentered
+ keycode 61 = slash question questiondown dead_hook Arabic_zah Arabic_question_mark slash question
+ keycode 62 = Shift_R NoSymbol Shift_R Shift_R
+ ...
+ +

+
+
+

- Details forthcoming + ...Work in progress...

+