NAME

       xxkb - switches and indicates a current keyboard layout.

SYNOPSIS

       xxkb

DESCRIPTION

       The  xxkb program shows the current keyboard layout (an XKB group) and allows to switch it
       with a mouse click. It has some additional features.  The xxkb remembers  the  layout  for
       each  application window and changes the keyboard state accordingly when the window gets a
       focus. The xxkb can place an additional button on a window title bar and that button is  a
       switcher  and an indicator for that separate window. If the keyboard map has more than two
       layouts the xxkb can simplify a switching using a two_state mode. In this  mode  the  xxkb
       allows  to  choose  two  layouts,  one  as a base layout and another one as an alternative
       layout and then switch the keyboard state  between  them  only.  Also  the  xxkb  supports
       applications lists which allow to tune its behavior for some separate applications.
         The xxkb works with any window manager.

USAGE

       Working  as an indicator the xxkb shows a current XKB layout using one of four pixmaps and
       changes the pixmap when you change a layout with the keyboard (using the key  or  the  key
       combination  specified  in  the  config  file as an XKB group switcher) or using any other
       application which able to change the XKB group. Also the xxkb shows the similar pixmaps on
       each  application  window  title  bar which are indicators for separate windows. Since the
       global indicator and the per window indicators duplicates each  other  you  can  hide  the
       global indicator or all per window indicators using configure options.
         Also  you  can  use the xxkb as a layout switcher using a mouse button click on the main
       xxkb window or one of the per window indicators.  In last case you switch the  layout  for
       the chosen application.

       MouseButton1
           The first button acts as a layout switcher. If the two_state mode is active the button
           click switches the current layout between two selected layouts (XKB groups). Otherwise
           it selects all possible layouts in cycle.

       MouseButton3
           When  the  two_state  mode  is  switched  on  the  third  button  allows  to choose an
           alternative layout. It selects all possible layouts in cycle and the layout  you  stop
           on  becomes  the  alternative layout. Without the two_state mode this button action is
           the same as the first button action.

       MouseButton2
           The second (middle) button action depends on the place where you click.  The click  on
           the  main  indicator  terminates  the  xxkb.  But  the  click on one of the per window
           indicators simply  removes  the  indicator  from  the  title  bar  and  excludes  that
           application  from a set of managed applications.  Also the second button allows you to
           add an application into one of three lists of the applications which should be ignored
           (see  the Applications lists options below). Clicking on the per window indicator when
           the Control key is pressed you add this application to the wm_class_class list. If the
           Shift  key  is  pressed  the button click adds the application to the wm_name list. If
           both keys are pressed the click adds the application to the  wm_class_name  list.   In
           all cases the updated lists will be saved in a per user config file ~/.xxkbrc.

CONFIGURE OPTIONS

       The xxkb reads all configure options from two files app-defaults/XXkb and ~/.xxkbrc.

Common options

       XXkb.image.path
           The directory where the xxkb searches pixmap files.

Main window options

       XXkb.mainwindow.enable
           switch  on the xxkb main window (yes by default). If a per window button mode switched
           on some users prefer to hide the main window of the xxkb.

       XXkb.mainwindow.appicon
           run xxkb as an animated icon. It is useful for window managers which allow  'to  dock'
           applications.

       XXkb.mainwindow.in_tray
           allow to dock xxkb into a system tray. A value is either true or false.

       XXkb.mainwindow.geometry
           the  geometry  (  WIDTHxHEIGHT{+-}XOFF{+-}YOFF  )  of the main window. Please read the
           GEOMETRY SPECIFICATIONS section of X(7) for details.

       XXkb.mainwindow.border.color
           color to be used when drawing window border.

       XXkb.mainwindow.border.width
           border width in pixels.

       XXkb.mainwindow.image.N
           pixmap file names for each indicated group N. If your symbols map has less  than  four
           groups  the  unused  group  icons  can be omitted. If the file name begins from '/' it
           means full path for the file. Otherwise it means the relative path beginning from  the
           XXkb.image.path value.

       XXkb.mainwindow.label.enable
           enable  labels to be printed instead of images. Group descriptions will be used if not
           overwritten by XXkb.mainwindow.label.text.N (where N is 1..4, group number) options.

       XXkb.mainwindow.label.text.N
           label for the specified group N.

       XXkb.mainwindow.label.background

       XXkb.mainwindow.label.foreground
           colors used to draw background and label text respectively.

       XXkb.mainwindow.label.font
           font to be used when drawing labels.

Operation mode options

       Since the xxkb can keep the keyboard state for each application and restore the state when
       the  focus  is  changed  there  are group of options which controls how the xxkb finds the
       application windows.

       XXkb.controls.add_when_start
           If this mode is switched on (default) the  xxkb  at  start  time  tries  to  find  all
           application already run.

       XXkb.controls.add_when_create
           In  this  mode  the  xxkb  gets  a new application window at time when the application
           creates it. It is the base mode  but  I  can't  guaranty  it  works  with  all  window
           managers.

       XXkb.controls.add_when_change
           In  this mode the xxkb doesn't catch the windows at their creation but adds windows to
           the managed windows list if the keyboard state changes when  the  window  is  focused.
           It's   an   additional   mode  (not  recommended)  and  may  be  useful  only  if  the
           add_when_create mode for some reason doesn't work.

       XXkb.controls.focusout
           It makes the xxkb reset the keyboard group when the focus leaves the window. The  mode
           makes sense with the add_when_change mode only.

       XXkb.controls.button_delete
           This mode (switched on by default) allows user to remove the per window button using a
           mouse middle button click. Although the xxkb tries to ignore  the  windows  where  the
           keyboard  layout switching doesn't make sense, such windows can still appear. Or there
           are windows where an user for some reason doesn't want to have the button.

       XXkb.controls.button_delete_and_forget
           This mode in addition to previous one makes xxkb to forget the window which button  is
           deleted.   It  means  the  xxkb  will  not remember the keyboard state changes in this
           window and restore this state when the window will be focused.

       XXkb.controls.two_state
           Switching between two chosen keyboard layouts only.  If the XKB symbols map  has  more
           than two groups and not all of them are needed for each application the xxkb allows to
           skip unneeded layouts at the layout switching. You can select  one  group  as  a  base
           group and another one as an alternative group and then switch between these two groups
           only.  The base group is common for all applications (usually it contains  ASCII)  but
           the  alternative  group can be chosen for each application window separately.  In this
           mode a mouse right button allows to select the alternative  group  and  a  mouse  left
           button  as  well as the key which configured as the layout switcher change the current
           state between two selected layouts only.
             This mode uses two additional config options:

       XXkb.group.base
           the base group (integer 1..4).

       XXkb.group.alt
           the default alternative group (integer 1..4).

The application window button options

       All these options make sense if the XXkb.button.enable switched on.

       XXkb.button.enable
           If turned on, the xxkb adds an additional button to a title bar of each managed window
           which  is  the  indicator  and  the layout switcher for that particular window.  These
           buttons are not usual window manager buttons but windows (with a pixmap) owned by  the
           xxkb  itself. It means that in some cases a user needs to tune the button size and the
           position for the button look like a window manager decoration element.

       XXkb.button.geometry
           the button geometry ( WIDTHxHEIGHT{+-}XOFF{+-}YOFF ).

       XXkb.button.image.N
           the pixmap file names (the same as for the XXkb.mainwindow.image.* options).

       XXkb.button.label.enable

       XXkb.button.label.text.N

       XXkb.button.label.background

       XXkb.button.label.foreground

       XXkb.button.label.font

       XXkb.button.border.color

       XXkb.button.border.width
           see description of their main window counterparts.

Bell options

       XXkb.bell.enable
           enables the keyboard bell when the layout changes.

       XXkb.bell.percent
           an argument value for the XBell call.

Applications lists options

       The xxkb allows to specify lists of applications that requires some special  actions.  The
       applications can be specified using their WM_CLASS or WM_NAME properties.
         A common form of such option is

       XXkb.app_list.property.action: an applications list

         The  action here can be one of ignore, start_alt or alt_groupn.  The ignore action means
       that the xxkb must ignore the windows of those applications and doesn't add  them  to  the
       managed  windows set. The start_alt action means that the xxkb must set the keyboard state
       to the alternative layout when the application starts.  And  the  alt_group1,  alt_group2,
       alt_group3  or  alt_group4  actions  allow  to  specify  the  alternative  layout for some
       applications if this layout  should  be  different  from  the  common  alternative  layout
       specified in the XXkb.group.alt option.
         The  property  can  be  one  of  wm_class_class, wm_class_name or wm_name.  The xxkb can
       identify an application using its window properties  WM_CLASS  or  WM_NAME.  The  WM_CLASS
       property  actually  consists  of two parts - a res_class and a res_name. Thus the property
       field specifies what property or part of property should be considered for the application
       identification.
         By  default all these lists are empty. A not empty list is a sequence of words separated
       by space/tab. The xxkb accepts an asterisk as a part of word.  Long lists can be continued
       to the next line using a backslash as the last char in the line.
         For example:
         XXkb.app_list.wm_name.ignore: Fvwm* *clock .br

                                       Xman

       XXkb.ignore.reverse
           This  option  changes  a meaning of the Xxkb.*.ignore  list. If the option switched on
           the ignore list becomes the list of windows which should  be  managed  but  all  other
           should be ignored.

AUTHOR

       Ivan Pascal