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 ## License
  53
  54 The program "indicator-keyboard-led.py" is released under the MIT License.
  55 Please refer to the file for the full text of the license.
  56
  57 The icon "icon.svg" is released to the public domain.
  58
  59 ## Credits
  60
  61 I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote
  62 [indicator-chars](https://github.com/tobyS/indicator-chars) which I used
  63 as a reference when writing this software.
  64
  65 The icon used in the indicator (icon.svg) is modified from the file
  66 "emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz)
  67 who released it to the public domain for the
  68 [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).
  69
  70 ---
  71
  72 ## Motivation
  73
  74 I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown
  75 on the panel. I didn't like the Notify OSD events either.
  76
  77 I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but
  78 I didn't like the fact that they refresh the indicator on a regular time
  79 interval (every *x* milliseconds) rather than on state changes (only when
  80 the locks are toggled).
  81
  82 I also thought it would be fun to be able to toggle the locks on-screen.
  83
  84 [ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock
  85 [lks]: https://github.com/SergKolo/lks-indicator
  86 [xbdmod]: https://github.com/sneetsher/indicator-xkbmod