X-Git-Url: https://adrianiainlam.tk/git/?a=blobdiff_plain;f=README.md;h=cf90a7ba69c88ef7a9ddabfa727e2944a78ee195;hb=HEAD;hp=111d461a29fa5129775a873db4b72d4b57482861;hpb=f462ecb9498e3525c8eea31664c2c03f32219e8d;p=indicator-keyboard-led.git diff --git a/README.md b/README.md index 111d461..cf90a7b 100644 --- a/README.md +++ b/README.md @@ -16,74 +16,80 @@ off. 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 -## Dependencies - - Python 3 (*) - - GTK+ 3 (*) - - AppIndicator 3 (*) - - Python 3 GObject introspection (python3-gi) - - xdotool + sudo add-apt-repository ppa:adrianiainlam/indicator-keyboard-led + sudo apt-get update + sudo apt-get install indicator-keyboard-led -Those marked with (*) are probably installed by default in recent Ubuntu -distributions. To install the rest, run: +After installation the postinst script will prompt you for preferences +configuration. These config are explained here: - sudo apt-get install python3-gi xdotool +### Order -## Usage - - 1. Install the dependencies listed above. - 2. Clone this repository. - 3. Add the script as a startup application. (Use option `--short` for short - appearance; use option `--order` to customize the order of the locks - displayed. See [Examples](#examples)) - 4. Run the script manually for the first time. (Alternatively, log out - and log in again.) - 5. 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. - 6. 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. - -## Examples - -![indicator default][sc1] -Default appearance. `python3 indicator-keyboard-led.py` - -![indicator short][sc3] -Short appearance. `python3 indicator-keyboard-led.py --short` +This option allows you to reorder the locks and also to hide +some locks if you don't need them. -![indicator CNS][sc4] -Order changed to Caps Num Scroll. -`python3 indicator-keyboard-led.py --order CNS` +Use a string consisting of zero or one occurrence of the +characters 'N', 'C' and 'S' to set this option. -![indicator NC][sc5] -Hide Scroll lock. `python3 indicator-keyboard-led.py --order NC` +For exampe, the default order is "Num Caps Scroll". +![Num Caps Scroll][sc1] -![indicator C short][sc6] -Show Caps lock only, short appearance. -`python3 indicator-keyboard-led.py --short --order C` +**CNS** changes this to "Caps Num Scroll". +![Caps Num Scroll][sc4] -![indicator default, French locale][sc7] -Default appearance in a French locale. -`LANGUAGE=fr_FR python3 indicator-keyboard-led.py` +**NC** hides Scroll lock from the default appearance. +![Num Caps][sc5] [sc1]: screenshots/sc1.png [sc2]: screenshots/sc2.png -[sc3]: screenshots/sc3.png [sc4]: screenshots/sc4.png [sc5]: screenshots/sc5.png -[sc6]: screenshots/sc6.png -[sc7]: screenshots/sc7.png -## Known bugs +### 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 + +### Indicator label does not show on Xfce / XUbuntu + +See [#6](https://github.com/adrianiainlam/indicator-keyboard-led/issues/6). + +### 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} + > 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 @@ -91,7 +97,7 @@ To solve this, do the following (assuming US keyboard): > > ... > modifier_map Mod3 { Scroll_Lock }; <==<< Add this line - > + > > include "level3(ralt_switch)" <==<< before this line > }; > @@ -110,19 +116,55 @@ 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. +Unfortunately, in order to work-around labels not being shown on newer +non-Unity-based Ubuntus, I have re-designed the indicators to be based +purely on icons instead. This means there will no longer be labels to +localize, and I instead have hardcoded icons. + +The icons are SVGs so you can still manually edit them if you want. +Look for the `` tag at the end of the SVGs. + +The menu items shown on click are still localized. + +I have included a screenshot below to show the old design (version 1.1) +which you can still install manually if you wish. + +> 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 "icon.svg" is released to the public domain. +The icons "indicator-keyboard-led*.svg" are released to the public domain. ## Credits @@ -130,8 +172,9 @@ 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 (icon.svg) is modified from the file -"emblem-readonly.svg" by [Jakub Steiner](http://jimmac.musichall.cz) +The icons used in the indicator (indicator-keyboard-led*.svg) are 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).