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