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