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 ## 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
  34 ## Usage
  35
  36  1. Install the dependencies listed above.
  37  2. Clone this repository.
  38  3. Add the script as a startup application. (Use option `--short` for short
  39     appearance; use option `--order` to customize the order of the locks
  40     displayed. See [Examples](#examples))
  41  4. Run the script manually for the first time. (Alternatively, log out
  42     and log in again.)
  43  5. The indicator should be shown at the top right corner, with a filled circle
  44     representing a lock turned on and an unfilled circle representing a lock
  45     turned off.
  46  6. Clicking on the indicator should result in a menu with the three locks.
  47     Clicking on the menu item would cause the corresponding lock to toggle.
  48
  49 ## Examples
  50
  51 ![indicator default][sc1]
  52 Default appearance. `python3 indicator-keyboard-led.py`
  53
  54 ![indicator short][sc3]
  55 Short appearance. `python3 indicator-keyboard-led.py --short`
  56
  57 ![indicator CNS][sc4]
  58 Order changed to Caps Num Scroll.
  59 `python3 indicator-keyboard-led.py --order CNS`
  60
  61 ![indicator NC][sc5]
  62 Hide Scroll lock. `python3 indicator-keyboard-led.py --order NC`
  63
  64 ![indicator C short][sc6]
  65 Show Caps lock only, short appearance.
  66 `python3 indicator-keyboard-led.py --short --order C`
  67
  68 ![indicator default, French locale][sc7]
  69 Default appearance in a French locale.
  70 `LANGUAGE=fr_FR python3 indicator-keyboard-led.py`
  71
  72 [sc1]: screenshots/sc1.png
  73 [sc2]: screenshots/sc2.png
  74 [sc3]: screenshots/sc3.png
  75 [sc4]: screenshots/sc4.png
  76 [sc5]: screenshots/sc5.png
  77 [sc6]: screenshots/sc6.png
  78 [sc7]: screenshots/sc7.png
  79
  80 ## Known bugs
  81
  82 It seems to be a common problem that Scroll Lock is not usable in Ubuntu.
  83 To solve this, do the following (assuming US keyboard):
  84
  85  >     # backup your symbols file
  86  >     sudo cp /usr/share/X11/xkb/symbols/us{,.distribution}
  87  >
  88  > Add the following line in the `xkb_symbols "basic" {` section. Do not worry
  89  > if that second line is not there, it is only there for some languages and
  90  > was not there for us on my system.
  91  >
  92  >     ...
  93  >         modifier_map Mod3   { Scroll_Lock }; <==<< Add this line
  94  >
  95  >         include "level3(ralt_switch)" <==<< before this line
  96  >     };
  97  >
  98  >
  99  > You may have to do the same in your other layouts if you switch between
 100  > languages.
 101  >
 102  > Also, there is a cache where xkb layouts live. You should clear it before
 103  > restarting your X server to check the new keyboard symbol file(s).
 104  >
 105  >     sudo dpkg-reconfigure xkb-data
 106
 107 *By Pykler and Giovanni Toraldo on AskUbuntu.* [Source][quotesrc]. Slightly
 108 modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums.
 109
 110 [origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201
 111 [quotesrc]: http://askubuntu.com/a/597757/274080
 112
 113 ## Localization
 114
 115 As motivated by Issue #1, this script has been localized to French (with
 116 the assistance of Wikipedia and Google Translate). Corrections to the
 117 translation, as well as translations to other languages, are welcome.
 118 Feel free to create a pull request or open an issue.
 119
 120 ## License
 121
 122 The program "indicator-keyboard-led.py" is released under the MIT License.
 123 Please refer to the file for the full text of the license.
 124
 125 The icon "icon.svg" is released to the public domain.
 126
 127 ## Credits
 128
 129 I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote
 130 [indicator-chars](https://github.com/tobyS/indicator-chars) which I used
 131 as a reference when writing this software.
 132
 133 The icon used in the indicator (icon.svg) is modified from the file
 134 "emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz)
 135 who released it to the public domain for the
 136 [Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).
 137
 138 ---
 139
 140 ## Motivation
 141
 142 I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown
 143 on the panel. I didn't like the Notify OSD events either.
 144
 145 I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but
 146 I didn't like the fact that they refresh the indicator on a regular time
 147 interval (every *x* milliseconds) rather than on state changes (only when
 148 the locks are toggled).
 149
 150 I also thought it would be fun to be able to toggle the locks on-screen.
 151
 152 [ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock
 153 [lks]: https://github.com/SergKolo/lks-indicator
 154 [xbdmod]: https://github.com/sneetsher/indicator-xkbmod