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

XXKB                                               24 Jun 2002                                           xxkb(1)