svkbd

simple virtual keyboard
git clone git://git.suckless.org/svkbd
Log | Files | Refs | README | LICENSE

README.md (4715B)


      1 SVKBD: Simple Virtual Keyboard
      2 =================================
      3 
      4 This is a simple virtual keyboard, intended to be used in environments,
      5 where no keyboard is available.
      6 
      7 Installation
      8 ------------
      9 
     10 	$ make
     11 	$ make install
     12 
     13 This will create by default `svkbd-mobile-intl`, which is svkbd using an international
     14 layout with multiple layers and overlays, and optimised for mobile devices.
     15 
     16 You can create svkbd for additional layouts by doing:
     17 
     18 	$ make LAYOUT=$layout
     19 
     20 This will take the file `layout.$layout.h` and create `svkbd-$layout`.
     21 `make install` will then pick up the new file and install it accordingly.
     22 
     23 Layouts
     24 ---------
     25 
     26 The following layouts are available:
     27 
     28 * **Mobile Layouts:**
     29     * ``mobile-intl`` - A small international layout optimised for mobile devices. This layout consists of multiple layers which
     30         can be switched on the fly, and overlays that appear on long-press of certain keys, adding input ability for
     31         diacritics and other variants, as well as some emoji. The layers are:
     32         * a basic qwerty layer
     33         * a layer for numeric input, arrows, and punctuation
     34         * a cyrillic layer (ЙЦУКЕН based); the э key is moved to an overlay on е
     35         * a dialer/numeric layer
     36         * an arrow layer
     37     * ``mobile-plain`` - This is a plain layout with only a qwerty layer and numeric/punctuation layer. It was
     38         originally made for [sxmo](https://sr.ht/~mil/Sxmo/).
     39     * ``mobile-simple`` - This is a more minimalistic layout that is more similar to what Android and iOS offer.
     40 * **Traditional layouts**:
     41     * ``en`` - An english layout without layers (QWERTY)
     42     * ``de`` - A german layout (QWERTZ)
     43     * ``ru`` - A russian layout (ЙЦУКЕН)
     44     * ``sh`` - A serbo-croatian layout using latin script (QWERTZ)
     45 
     46 Usage
     47 -----
     48 
     49 	$ svkbd-mobile-intl
     50 
     51 This will open svkbd at the bottom of the screen, showing the default
     52 international layout.
     53 
     54 	$ svkbd-mobile-intl -d
     55 
     56 This tells svkbd to announce itself being a dock window, which then
     57 is managed differently between different window managers. If using dwm
     58 and the dock patch, then this will make svkbd being managed by dwm and
     59 some space of the screen being reserved for it.
     60 
     61 	$ svkbd-mobile-intl -g 400x200+1+1
     62 
     63 This will start svkbd-intl with a size of 400x200 and at the upper left
     64 window corner.
     65 
     66 For layouts that consist of multiple layers, you can enable layers on program start through either the ``-l`` flag or
     67 through the ``SVKBD_LAYERS`` environment variable.  They both take a comma separated list of layer names (as defined in
     68 your ``layout.*.h``). Use the ``↺`` button in the bottom-left to cycle through all the layers.
     69 
     70 Some layouts come with overlays that will show when certain keys are hold pressed for a longer time. For
     71 example, a long press on the ``a`` key will enable an overview showing all kinds of diacritic combinations for ``a``.
     72 
     73 Overlay functionality interferes with the ability to hold a key and have it outputted repeatedly.  You can disable
     74 overlay functionality with the ``-O`` flag or by setting the environment variable ``SVKBD_ENABLEOVERLAYS=0``. There is
     75 also a key on the function layer of the keyboard itself to enable/disable this behaviour on the fly. Its label shows
     76 ``≅`` when the overlay functionality is enabled and ``≇`` when not.
     77 
     78 Svkbd has been optimised for use on mobile devices with a touchscreen and implements press-on-release
     79 behaviour (which can be disabled), it also works fine on normal desktop systems with a regular mouse.
     80 
     81 Advanced Usage
     82 ---------------
     83 
     84 Svkbd has an extra output mode where all keypresses are printed to standard output. Optionally, you can also disable the
     85 default X11 keypress emulation. This gives you the freedom to use svkbd in other contexts and use simple pipes to
     86 connect it to other tools:
     87 
     88 
     89 	$ svkbd-mobile-intl -n -o | cowsay
     90 
     91 This becomes especially useful if you want things like haptic feedback or audio feedback upon keypress. This is
     92 deliberately not implemented in svkbd itself (we want to keep things simple after all), but can be accomplished using
     93 the external tool [clickclack](https://git.sr.ht/~proycon/clickclack):
     94 
     95 	$ svkbd-mobile-intl -o | clickclack -V -f keypress.wav
     96 
     97 Notes
     98 ---------
     99 
    100 This virtual keyboard does not actually modify the X keyboard layout, the ``mobile-intl``, ``mobile-plain``,
    101 ``mobile-simple`` and ``en`` layouts simply rely on a standard US QWERTY layout (setxkbmap us) being activated, the
    102 other layouts (``de``, ``ru``, ``sh``) require their respective XKB keymaps to be active.
    103 
    104 If you use another XKB layout you will get unpredictable output that does not match the labels on the virtual keycaps!
    105 
    106 Repository
    107 ----------
    108 
    109 	git clone https://git.suckless.org/svkbd