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 **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
  12 ## Screenshots
  13
  14 ![indicator default][sc1]
  15 Default appearance of the indicator with Num lock on and Caps and Scroll locks
  16 off.
  17
  18 ![indicator menu][sc2]
  19 Menu of the indicator, shown on click. The locks can be toggled by clicking
  20 the respective item in the menu.
  21
  22 ![indicator short][sc3]
  23 Alternative (short) appearance of the indicator.
  24
  25 ## Installation from Ubuntu PPA
  26
  27     sudo add-apt-repository ppa:adrianiainlam/indicator-keyboard-led
  28     sudo apt-get update
  29     sudo apt-get install indicator-keyboard-led
  30
  31 After installation the postinst script will prompt you for preferences
  32 configuration. These config are explained here:
  33
  34 ### Short label
  35
  36 The default appearance of the indicator has long labels:
  37 ![⚫Num ⚫Caps ⚫Scroll][sc1]
  38
  39 On small displays it may be preferable to use short labels:
  40 ![⚫N ⚫C ⚫S][sc3]
  41
  42 ### Order
  43
  44 This option allows you to reorder the locks and also to hide
  45 some locks if you don't need them.
  46
  47 Use a string consisting of zero or one occurrence of the
  48 characters 'N', 'C' and 'S' to set this option.
  49
  50 For exampe, the default order is "Num Caps Scroll".
  51 ![⚫Num ⚫Caps ⚫Scroll][sc1]
  52
  53 **CNS** changes this to "Caps Num Scroll".
  54 ![⚫Caps ⚫Num ⚫Scroll][sc4]
  55
  56 **NC** hides Scroll lock from the default appearance.
  57 ![⚫Num ⚫Caps][sc5]
  58
  59 **C**, combined with the previous *short* option,
  60 would give a very compact Caps lock indicator.
  61 ![⚫C][sc6]
  62
  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
  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
  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
  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.
  99
 100 ## Known bugs / Troubleshooting
 101
 102 ### Indicator label does not show on Xfce / XUbuntu
 103
 104 See [#6](https://github.com/adrianiainlam/indicator-keyboard-led/issues/6).
 105
 106 ### Pressing Scroll Lock does nothing
 107
 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
 138
 139 ### Scroll lock does not appear on indicator
 140
 141 Your installed GTK+ version is probably older than 3.18, which
 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.
 146
 147 If your installed GTK+ is 3.18+ then please file a bug report.
 148
 149 [gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state
 150
 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.
 156
 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.
 163
 164 ![indicator default, French locale][sc7]
 165 Default appearance in a French locale.
 166
 167 [sc7]: screenshots/sc7.png
 168
 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
 174 The icon "indicator-keyboard-led.svg" is released to the public domain.
 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
 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)
 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