README.md

   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
  11 ![indicator default][sc1]
  12 Default appearance of the indicator with Num lock on and Caps and Scroll locks
  13 off.
  14
  15 ![indicator menu][sc2]
  16 Menu of the indicator, shown on click. The locks can be toggled by clicking
  17 the respective item in the menu.
  18
  19 ![indicator short][sc3]
  20 Alternative (short) appearance of the indicator.
  21
  22 [sc1]: screenshots/sc1.png
  23 [sc2]: screenshots/sc2.png
  24 [sc3]: screenshots/sc3.png
  25
  26 ## Dependencies
  27  - Python 3 (*)
  28  - GTK+ 3 (*)
  29  - AppIndicator 3 (*)
  30  - Python 3 GObject introspection (python3-gi)
  31  - xdotool
  32
  33 Those marked with (*) are probably installed by default in recent Ubuntu
  34 distributions. To install the rest, run:
  35
  36     sudo apt-get install python3-gi xdotool
  37
  38 ## Usage
  39
  40  1. Install the dependencies listed above.
  41  2. Clone this repository.
  42  3. Add the script as a startup application. (Use option `--short` for short
  43     appearance if desired.)
  44  4. Run the script manually for the first time. (Alternatively, log out
  45     and log in again.)
  46  5. The indicator should be shown at the top right corner, with a filled circle
  47     representing a lock turned on and an unfilled circle representing a lock
  48     turned off.
  49  6. Clicking on the indicator should result in a menu with the three locks.
  50     Clicking on the menu item would cause the corresponding lock to toggle.
  51
  52 ## Known bugs
  53
  54 It seems to be a common problem that Scroll Lock is not usable in Ubuntu.
  55 To solve this, do the following (assuming US keyboard):
  56
  57  >     # backup your symbols file
  58  >     sudo cp /usr/share/X11/xkb/symbols/us{,.distribution}
  59  >
  60  > Add the following line in the `xkb_symbols "basic" {` section. Do not worry
  61  > if that second line is not there, it is only there for some languages and
  62  > was not there for us on my system.
  63  >
  64  >     ...
  65  >         modifier_map Mod3   { Scroll_Lock }; <==<< Add this line
  66  >
  67  >         include "level3(ralt_switch)" <==<< before this line
  68  >     };
  69  >
  70  >
  71  > You may have to do the same in your other layouts if you switch between
  72  > languages.
  73  >
  74  > Also, there is a cache where xkb layouts live. You should clear it before
  75  > restarting your X server to check the new keyboard symbol file(s).
  76  >
  77  >     sudo dpkg-reconfigure xkb-data
  78
  79 *By Pykler and Giovanni Toraldo on AskUbuntu.* [Source][quotesrc]. Slightly
  80 modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums.
  81
  82 [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201
  83 [quotesrc]: http://askubuntu.com/a/597757/274080
  84
  85
  86 ## License
  87
  88 The program "indicator-keyboard-led.py" is released under the MIT License.
  89 Please refer to the file for the full text of the license.
  90
  91 The icon "icon.svg" is released to the public domain.
  92
  93 ## Credits
  94
  95 I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote
  96 [indicator-chars](https://github.com/tobyS/indicator-chars) which I used
  97 as a reference when writing this software.
  98
  99 The icon used in the indicator (icon.svg) is modified from the file
 100 "emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz)
 101 who released it to the public domain for the
 102 [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).
 103
 104 ---
 105
 106 ## Motivation
 107
 108 I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown
 109 on the panel. I didn't like the Notify OSD events either.
 110
 111 I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but
 112 I didn't like the fact that they refresh the indicator on a regular time
 113 interval (every *x* milliseconds) rather than on state changes (only when
 114 the locks are toggled).
 115
 116 I also thought it would be fun to be able to toggle the locks on-screen.
 117
 118 [ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock
 119 [lks]: https://github.com/SergKolo/lks-indicator
 120 [xbdmod]: https://github.com/sneetsher/indicator-xkbmod