[indicator-keyboard-led.git] / README.md

# indicator-keyboard-led - simulate keyboard lock keys LED

This is a Unity application indicator designed for keyboards without lock
keys LED. It allows the user to check the state of the three locks (Caps lock,
Num lock and Scroll lock) without requiring any mouse or keyboard action. It
also allows the lock keys to be toggled with mouse clicks, which could be
useful for keyboards without Scroll lock keys or malfunctioning keyboards.

## Screenshots

![indicator default][sc1]  
Default appearance of the indicator with Num lock on and Caps and Scroll locks
off.

![indicator menu][sc2]  
Menu of the indicator, shown on click. The locks can be toggled by clicking
the respective item in the menu.

![indicator short][sc3]  
Alternative (short) appearance of the indicator.

## Installation from Ubuntu PPA

* This is a work in progress. *

After installation the postinst script will prompt you for preferences
configuration. These config are explained here:

### Short label

The default appearance of the indicator has long labels:  
![⚫Num ⚫Caps ⚫Scroll][sc1]

On small displays it may be preferable to use short labels:  
![⚫N ⚫C ⚫S][sc3]

### Order

This option allows you to reorder the locks and also to hide
some locks if you don't need them.

Use a string consisting of zero or one occurrence of the
characters 'N', 'C' and 'S' to set this option.

For exampe, the default order is "Num Caps Scroll".  
![⚫Num ⚫Caps ⚫Scroll][sc1]

**CNS** changes this to "Caps Num Scroll".  
![⚫Caps ⚫Num ⚫Scroll][sc4]

**NC** hides Scroll lock from the default appearance.  
![⚫Num ⚫Caps][sc5]

**C**, combined with the previous *short* option,
would give a very compact Caps lock indicator.  
![⚫C][sc6]

[sc1]: screenshots/sc1.png
[sc2]: screenshots/sc2.png
[sc3]: screenshots/sc3.png
[sc4]: screenshots/sc4.png
[sc5]: screenshots/sc5.png
[sc6]: screenshots/sc6.png

### xdotool

`xdotool` is used to emulate key strokes to set/unset locks on mouse clicks.
If you installed xdotool at a non-default location, please provide its full
path (e.g. /home/user/bin/xdotool) with this option.

If it is installed in your $PATH environment variable, or not installed at
all, leave this option blank.

### Changing your mind

If you want to change these settings afterwards, simply run

    sudo dpkg-reconfigure indicator-keyboard-led

and you will be prompted again.

## Usage

The indicator will be configured to autostart on log-in. To start using the
indicator after installation, log-out and log-in again, or manually start
the indicator (search for "indicator-keyboard-led" in the dash).

The indicator should be shown at the top right corner, with a filled circle
representing a lock turned on and an unfilled circle representing a lock
turned off.

Clicking on the indicator should result in a menu with the three locks.
Clicking on the menu item would cause the corresponding lock to toggle.

## Known bugs / Troubleshooting

### Pressing Scroll Lock does nothing

It seems to be a common problem that Scroll Lock is not usable in Ubuntu.
To solve this, do the following (assuming US keyboard):

 >     # backup your symbols file
 >     sudo cp /usr/share/X11/xkb/symbols/us{,.distribution} 
 >
 > Add the following line in the `xkb_symbols "basic" {` section. Do not worry
 > if that second line is not there, it is only there for some languages and
 > was not there for us on my system.
 >
 >     ...
 >         modifier_map Mod3   { Scroll_Lock }; <==<< Add this line
 > 
 >         include "level3(ralt_switch)" <==<< before this line
 >     };
 >
 >
 > You may have to do the same in your other layouts if you switch between
 > languages.
 >
 > Also, there is a cache where xkb layouts live. You should clear it before
 > restarting your X server to check the new keyboard symbol file(s).
 >
 >     sudo dpkg-reconfigure xkb-data

*By Pykler and Giovanni Toraldo on AskUbuntu.* [Source][quotesrc]. Slightly
modified. [Original source][origsrc] by dm+ on PCLinuxOS-Forums.

[origsrc]: http://www.pclinuxos.com/forum/index.php/topic,125690.msg1052201.html?PHPSESSID=2qsv83lve6dgd0ivq14bfcjc30#msg1052201
[quotesrc]: http://askubuntu.com/a/597757/274080

### Scroll lock does not appear on indicator

Your installed GTK+ version is probably older than 3.18, which
does not support [`gdk_keymap_get_scroll_lock_state ()`][gtkdoc-scroll].
The earliest Ubuntu release that supports GTK+ 3.18 is 16.04 (Xenial).
If you use an older version, Scroll lock functionality will be disabled.
Please consider upgrading your system if you really want Scroll lock.

If your installed GTK+ is 3.18+ then please file a bug report.

[gtkdoc-scroll]: https://developer.gnome.org/gdk3/stable/gdk3-Keyboard-Handling.html#gdk-keymap-get-scroll-lock-state

### Drop-down menu only has "Quit", the clickable locks do not appear

Please verify that xdotool is installed in your PATH with the executable
bit set. If you provided a custom path to xdotool please verify that it
is correct and is an executable regular file.

## Localization

As motivated by Issue #1, this script has been localized to French (with
the assistance of Wikipedia and Google Translate). Corrections to the
translation, as well as translations to other languages, are welcome.
Feel free to create a pull request or open an issue.

![indicator default, French locale][sc7]  
Default appearance in a French locale.

[sc7]: screenshots/sc7.png

## License

The program "indicator-keyboard-led.py" is released under the MIT License.
Please refer to the file for the full text of the license.

The icon "indicator-keyboard-led.svg" is released to the public domain.

## Credits

I would like to thank [Tobias Schlitt](https://github.com/tobyS), who wrote
[indicator-chars](https://github.com/tobyS/indicator-chars) which I used
as a reference when writing this software.

The icon used in the indicator (indicator-keyboard-led.svg) is modified
from the file "emblem-readonly.svg" by
[Jakub Steiner](http://jimmac.musichall.cz)
who released it to the public domain for the
[Tango Icon Library](http://tango.freedesktop.org/Tango_Icon_Library).

---

## Motivation

I was a user of [indicator-keylock][ind-kl], but only one key lock can be shown
on the panel. I didn't like the Notify OSD events either.

I then came across [lks-indicator][lks] and [indicator-xbdmod][xbdmod], but
I didn't like the fact that they refresh the indicator on a regular time
interval (every *x* milliseconds) rather than on state changes (only when
the locks are toggled).

I also thought it would be fun to be able to toggle the locks on-screen.

[ind-kl]: https://launchpad.net/~tsbarnes/+archive/ubuntu/indicator-keylock
[lks]: https://github.com/SergKolo/lks-indicator
[xbdmod]: https://github.com/sneetsher/indicator-xkbmod
Commit	Line	Data
	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