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