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 | ||
9429819b AIL |
9 | **Note**: This indicator is known to not work on Xfce / Xubuntu. |
10 | For more details, see [#6](https://github.com/adrianiainlam/indicator-keyboard-led/issues/6). | |
11 | ||
fc1c0791 AIL |
12 | ## Screenshots |
13 | ||
9900bce1 | 14 | ![indicator default][sc1] |
fc1c0791 AIL |
15 | Default appearance of the indicator with Num lock on and Caps and Scroll locks |
16 | off. | |
17 | ||
9900bce1 | 18 | ![indicator menu][sc2] |
fc1c0791 AIL |
19 | Menu of the indicator, shown on click. The locks can be toggled by clicking |
20 | the respective item in the menu. | |
21 | ||
9900bce1 | 22 | ![indicator short][sc3] |
fc1c0791 AIL |
23 | Alternative (short) appearance of the indicator. |
24 | ||
017d8bd1 | 25 | ## Installation from Ubuntu PPA |
fc1c0791 | 26 | |
947c2183 AIL |
27 | sudo add-apt-repository ppa:adrianiainlam/indicator-keyboard-led |
28 | sudo apt-get update | |
29 | sudo apt-get install indicator-keyboard-led | |
fc1c0791 | 30 | |
017d8bd1 AIL |
31 | After installation the postinst script will prompt you for preferences |
32 | configuration. These config are explained here: | |
fc1c0791 | 33 | |
017d8bd1 | 34 | ### Short label |
73e49461 | 35 | |
017d8bd1 AIL |
36 | The default appearance of the indicator has long labels: |
37 | ![⚫Num ⚫Caps ⚫Scroll][sc1] | |
73e49461 | 38 | |
017d8bd1 AIL |
39 | On small displays it may be preferable to use short labels: |
40 | ![⚫N ⚫C ⚫S][sc3] | |
fc1c0791 | 41 | |
017d8bd1 | 42 | ### Order |
170ff396 | 43 | |
017d8bd1 AIL |
44 | This option allows you to reorder the locks and also to hide |
45 | some locks if you don't need them. | |
170ff396 | 46 | |
017d8bd1 AIL |
47 | Use a string consisting of zero or one occurrence of the |
48 | characters 'N', 'C' and 'S' to set this option. | |
170ff396 | 49 | |
017d8bd1 AIL |
50 | For exampe, the default order is "Num Caps Scroll". |
51 | ![⚫Num ⚫Caps ⚫Scroll][sc1] | |
170ff396 | 52 | |
017d8bd1 AIL |
53 | **CNS** changes this to "Caps Num Scroll". |
54 | ![⚫Caps ⚫Num ⚫Scroll][sc4] | |
170ff396 | 55 | |
017d8bd1 AIL |
56 | **NC** hides Scroll lock from the default appearance. |
57 | ![⚫Num ⚫Caps][sc5] | |
170ff396 | 58 | |
017d8bd1 AIL |
59 | **C**, combined with the previous *short* option, |
60 | would give a very compact Caps lock indicator. | |
61 | ![⚫C][sc6] | |
f462ecb9 | 62 | |
170ff396 AIL |
63 | [sc1]: screenshots/sc1.png |
64 | [sc2]: screenshots/sc2.png | |
65 | [sc3]: screenshots/sc3.png | |
66 | [sc4]: screenshots/sc4.png | |
67 | [sc5]: screenshots/sc5.png | |
68 | [sc6]: screenshots/sc6.png | |
017d8bd1 AIL |
69 | |
70 | ### xdotool | |
71 | ||
72 | `xdotool` is used to emulate key strokes to set/unset locks on mouse clicks. | |
73 | If you installed xdotool at a non-default location, please provide its full | |
74 | path (e.g. /home/user/bin/xdotool) with this option. | |
75 | ||
76 | If it is installed in your $PATH environment variable, or not installed at | |
77 | all, leave this option blank. | |
78 | ||
79 | ### Changing your mind | |
80 | ||
81 | If you want to change these settings afterwards, simply run | |
82 | ||
83 | sudo dpkg-reconfigure indicator-keyboard-led | |
84 | ||
85 | and you will be prompted again. | |
86 | ||
87 | ## Usage | |
88 | ||
cd02f43e AIL |
89 | The indicator will be configured to autostart on log-in. To start using the |
90 | indicator after installation, log-out and log-in again, or manually start | |
91 | the indicator (search for "indicator-keyboard-led" in the dash). | |
92 | ||
017d8bd1 AIL |
93 | The indicator should be shown at the top right corner, with a filled circle |
94 | representing a lock turned on and an unfilled circle representing a lock | |
95 | turned off. | |
96 | ||
97 | Clicking on the indicator should result in a menu with the three locks. | |
98 | Clicking on the menu item would cause the corresponding lock to toggle. | |
170ff396 | 99 | |
94a2b01e | 100 | ## Known bugs / Troubleshooting |
9900bce1 | 101 | |
9429819b AIL |
102 | ### Indicator label does not show on Xfce / XUbuntu |
103 | ||
104 | See [#6](https://github.com/adrianiainlam/indicator-keyboard-led/issues/6). | |
105 | ||
73e49461 AIL |
106 | ### Pressing Scroll Lock does nothing |
107 | ||
9900bce1 AIL |
108 | It seems to be a common problem that Scroll Lock is not usable in Ubuntu. |
109 | To solve this, do the following (assuming US keyboard): | |
110 | ||
111 | > # backup your symbols file | |
112 | > sudo cp /usr/share/X11/xkb/symbols/us{,.distribution} | |
113 | > | |
114 | > Add the following line in the `xkb_symbols "basic" {` section. Do not worry | |
115 | > if that second line is not there, it is only there for some languages and | |
116 | > was not there for us on my system. | |
117 | > | |
118 | > ... | |
119 | > modifier_map Mod3 { Scroll_Lock }; <==<< Add this line | |
120 | > | |
121 | > include "level3(ralt_switch)" <==<< before this line | |
122 | > }; | |
123 | > | |
124 | > | |
125 | > You may have to do the same in your other layouts if you switch between | |
126 | > languages. | |
127 | > | |
128 | > Also, there is a cache where xkb layouts live. You should clear it before | |
129 | > restarting your X server to check the new keyboard symbol file(s). | |
130 | > | |
131 | > sudo dpkg-reconfigure xkb-data | |
132 | ||
133 | *By Pykler and Giovanni Toraldo on AskUbuntu.* [Source][quotesrc]. Slightly | |
134 | modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums. | |
135 | ||
136 | [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201 | |
137 | [quotesrc]: http://askubuntu.com/a/597757/274080 | |
f462ecb9 | 138 | |
94a2b01e | 139 | ### Scroll lock does not appear on indicator |
73e49461 | 140 | |
94a2b01e | 141 | Your installed GTK+ version is probably older than 3.18, which |
017d8bd1 AIL |
142 | does not support [`gdk_keymap_get_scroll_lock_state ()`][gtkdoc-scroll]. |
143 | The earliest Ubuntu release that supports GTK+ 3.18 is 16.04 (Xenial). | |
144 | If you use an older version, Scroll lock functionality will be disabled. | |
145 | Please consider upgrading your system if you really want Scroll lock. | |
73e49461 | 146 | |
94a2b01e | 147 | If your installed GTK+ is 3.18+ then please file a bug report. |
73e49461 | 148 | |
017d8bd1 AIL |
149 | [gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state |
150 | ||
94a2b01e AIL |
151 | ### Drop-down menu only has "Quit", the clickable locks do not appear |
152 | ||
153 | Please verify that xdotool is installed in your PATH with the executable | |
154 | bit set. If you provided a custom path to xdotool please verify that it | |
155 | is correct and is an executable regular file. | |
73e49461 | 156 | |
f462ecb9 AIL |
157 | ## Localization |
158 | ||
159 | As motivated by Issue #1, this script has been localized to French (with | |
160 | the assistance of Wikipedia and Google Translate). Corrections to the | |
161 | translation, as well as translations to other languages, are welcome. | |
162 | Feel free to create a pull request or open an issue. | |
9900bce1 | 163 | |
017d8bd1 AIL |
164 | ![indicator default, French locale][sc7] |
165 | Default appearance in a French locale. | |
166 | ||
167 | [sc7]: screenshots/sc7.png | |
168 | ||
fc1c0791 AIL |
169 | ## License |
170 | ||
171 | The program "indicator-keyboard-led.py" is released under the MIT License. | |
172 | Please refer to the file for the full text of the license. | |
173 | ||
017d8bd1 | 174 | The icon "indicator-keyboard-led.svg" is released to the public domain. |
fc1c0791 AIL |
175 | |
176 | ## Credits | |
177 | ||
178 | I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote | |
179 | [indicator-chars](https://github.com/tobyS/indicator-chars) which I used | |
180 | as a reference when writing this software. | |
181 | ||
017d8bd1 AIL |
182 | The icon used in the indicator (indicator-keyboard-led.svg) is modified |
183 | from the file "emblem-readonly.svg" by | |
184 | [Jakub Steiner](http://jimmac.musichall.cz) | |
fc1c0791 AIL |
185 | who released it to the public domain for the |
186 | [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library). | |
187 | ||
188 | --- | |
189 | ||
190 | ## Motivation | |
191 | ||
192 | I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown | |
193 | on the panel. I didn't like the Notify OSD events either. | |
194 | ||
195 | I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but | |
196 | I didn't like the fact that they refresh the indicator on a regular time | |
197 | interval (every *x* milliseconds) rather than on state changes (only when | |
198 | the locks are toggled). | |
199 | ||
200 | I also thought it would be fun to be able to toggle the locks on-screen. | |
201 | ||
202 | [ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock | |
203 | [lks]: https://github.com/SergKolo/lks-indicator | |
204 | [xbdmod]: https://github.com/sneetsher/indicator-xkbmod |