Commit | Line | Data |
---|---|---|
fc1c0791 AIL |
1 | # indicator-keyboard-led - simulate keyboard lock keys LED |
2 | ||
3 | This is a Unity application indicator designed for keyboards without lock | |
4 | keys LED. It allows the user to check the state of the three locks (Caps lock, | |
5 | Num lock and Scroll lock) without requiring any mouse or keyboard action. It | |
6 | also allows the lock keys to be toggled with mouse clicks, which could be | |
7 | useful for keyboards without Scroll lock keys or malfunctioning keyboards. | |
8 | ||
9 | ## Screenshots | |
10 | ||
9900bce1 | 11 | ![indicator default][sc1] |
fc1c0791 AIL |
12 | Default appearance of the indicator with Num lock on and Caps and Scroll locks |
13 | off. | |
14 | ||
9900bce1 | 15 | ![indicator menu][sc2] |
fc1c0791 AIL |
16 | Menu of the indicator, shown on click. The locks can be toggled by clicking |
17 | the respective item in the menu. | |
18 | ||
9900bce1 | 19 | ![indicator short][sc3] |
fc1c0791 AIL |
20 | Alternative (short) appearance of the indicator. |
21 | ||
fc1c0791 AIL |
22 | ## Dependencies |
23 | - Python 3 (*) | |
24 | - GTK+ 3 (*) | |
25 | - AppIndicator 3 (*) | |
26 | - Python 3 GObject introspection (python3-gi) | |
27 | - xdotool | |
28 | ||
29 | Those marked with (*) are probably installed by default in recent Ubuntu | |
30 | distributions. To install the rest, run: | |
31 | ||
32 | sudo apt-get install python3-gi xdotool | |
33 | ||
73e49461 AIL |
34 | **Note**: [`gdk_keymap_get_scroll_lock_state ()`][gtkdoc-scroll] is only |
35 | available since GTK+ 3.18. The earliest Ubuntu release that supports | |
94a2b01e AIL |
36 | GTK+ 3.18 is 16.04 (Xenial). This means that if you use an older version, |
37 | scroll lock functionality will be disabled. | |
73e49461 AIL |
38 | |
39 | [gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state | |
40 | ||
fc1c0791 AIL |
41 | ## Usage |
42 | ||
43 | 1. Install the dependencies listed above. | |
44 | 2. Clone this repository. | |
45 | 3. Add the script as a startup application. (Use option `--short` for short | |
170ff396 AIL |
46 | appearance; use option `--order` to customize the order of the locks |
47 | displayed. See [Examples](#examples)) | |
fc1c0791 AIL |
48 | 4. Run the script manually for the first time. (Alternatively, log out |
49 | and log in again.) | |
50 | 5. The indicator should be shown at the top right corner, with a filled circle | |
51 | representing a lock turned on and an unfilled circle representing a lock | |
52 | turned off. | |
53 | 6. Clicking on the indicator should result in a menu with the three locks. | |
54 | Clicking on the menu item would cause the corresponding lock to toggle. | |
55 | ||
170ff396 AIL |
56 | ## Examples |
57 | ||
58 | ![indicator default][sc1] | |
59 | Default appearance. `python3 indicator-keyboard-led.py` | |
60 | ||
61 | ![indicator short][sc3] | |
62 | Short appearance. `python3 indicator-keyboard-led.py --short` | |
63 | ||
64 | ![indicator CNS][sc4] | |
65 | Order changed to Caps Num Scroll. | |
66 | `python3 indicator-keyboard-led.py --order CNS` | |
67 | ||
68 | ![indicator NC][sc5] | |
94a2b01e | 69 | Hide Scroll lock, also the default appearance if Scroll lock is not supported. `python3 indicator-keyboard-led.py --order NC` |
170ff396 | 70 | |
a4c6e387 | 71 | ![indicator C short][sc6] |
170ff396 AIL |
72 | Show Caps lock only, short appearance. |
73 | `python3 indicator-keyboard-led.py --short --order C` | |
74 | ||
f462ecb9 AIL |
75 | ![indicator default, French locale][sc7] |
76 | Default appearance in a French locale. | |
77 | `LANGUAGE=fr_FR python3 indicator-keyboard-led.py` | |
78 | ||
170ff396 AIL |
79 | [sc1]: screenshots/sc1.png |
80 | [sc2]: screenshots/sc2.png | |
81 | [sc3]: screenshots/sc3.png | |
82 | [sc4]: screenshots/sc4.png | |
83 | [sc5]: screenshots/sc5.png | |
84 | [sc6]: screenshots/sc6.png | |
f462ecb9 | 85 | [sc7]: screenshots/sc7.png |
170ff396 | 86 | |
94a2b01e | 87 | ## Known bugs / Troubleshooting |
9900bce1 | 88 | |
73e49461 AIL |
89 | ### Pressing Scroll Lock does nothing |
90 | ||
9900bce1 AIL |
91 | It seems to be a common problem that Scroll Lock is not usable in Ubuntu. |
92 | To solve this, do the following (assuming US keyboard): | |
93 | ||
94 | > # backup your symbols file | |
95 | > sudo cp /usr/share/X11/xkb/symbols/us{,.distribution} | |
96 | > | |
97 | > Add the following line in the `xkb_symbols "basic" {` section. Do not worry | |
98 | > if that second line is not there, it is only there for some languages and | |
99 | > was not there for us on my system. | |
100 | > | |
101 | > ... | |
102 | > modifier_map Mod3 { Scroll_Lock }; <==<< Add this line | |
103 | > | |
104 | > include "level3(ralt_switch)" <==<< before this line | |
105 | > }; | |
106 | > | |
107 | > | |
108 | > You may have to do the same in your other layouts if you switch between | |
109 | > languages. | |
110 | > | |
111 | > Also, there is a cache where xkb layouts live. You should clear it before | |
112 | > restarting your X server to check the new keyboard symbol file(s). | |
113 | > | |
114 | > sudo dpkg-reconfigure xkb-data | |
115 | ||
116 | *By Pykler and Giovanni Toraldo on AskUbuntu.* [Source][quotesrc]. Slightly | |
117 | modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums. | |
118 | ||
119 | [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201 | |
120 | [quotesrc]: http://askubuntu.com/a/597757/274080 | |
f462ecb9 | 121 | |
94a2b01e | 122 | ### Scroll lock does not appear on indicator |
73e49461 | 123 | |
94a2b01e AIL |
124 | Your installed GTK+ version is probably older than 3.18, which |
125 | does not support `get_scroll_lock_state`. Please consider upgrading | |
126 | your system if you really want Scroll lock functionality. | |
73e49461 | 127 | |
94a2b01e | 128 | If your installed GTK+ is 3.18+ then please file a bug report. |
73e49461 | 129 | |
94a2b01e AIL |
130 | ### Drop-down menu only has "Quit", the clickable locks do not appear |
131 | ||
132 | Please verify that xdotool is installed in your PATH with the executable | |
133 | bit set. If you provided a custom path to xdotool please verify that it | |
134 | is correct and is an executable regular file. | |
73e49461 | 135 | |
f462ecb9 AIL |
136 | ## Localization |
137 | ||
138 | As motivated by Issue #1, this script has been localized to French (with | |
139 | the assistance of Wikipedia and Google Translate). Corrections to the | |
140 | translation, as well as translations to other languages, are welcome. | |
141 | Feel free to create a pull request or open an issue. | |
9900bce1 | 142 | |
fc1c0791 AIL |
143 | ## License |
144 | ||
145 | The program "indicator-keyboard-led.py" is released under the MIT License. | |
146 | Please refer to the file for the full text of the license. | |
147 | ||
148 | The icon "icon.svg" is released to the public domain. | |
149 | ||
150 | ## Credits | |
151 | ||
152 | I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote | |
153 | [indicator-chars](https://github.com/tobyS/indicator-chars) which I used | |
154 | as a reference when writing this software. | |
155 | ||
156 | The icon used in the indicator (icon.svg) is modified from the file | |
157 | "emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz) | |
158 | who released it to the public domain for the | |
159 | [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library). | |
160 | ||
161 | --- | |
162 | ||
163 | ## Motivation | |
164 | ||
165 | I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown | |
166 | on the panel. I didn't like the Notify OSD events either. | |
167 | ||
168 | I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but | |
169 | I didn't like the fact that they refresh the indicator on a regular time | |
170 | interval (every *x* milliseconds) rather than on state changes (only when | |
171 | the locks are toggled). | |
172 | ||
173 | I also thought it would be fun to be able to toggle the locks on-screen. | |
174 | ||
175 | [ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock | |
176 | [lks]: https://github.com/SergKolo/lks-indicator | |
177 | [xbdmod]: https://github.com/sneetsher/indicator-xkbmod |