unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



dxkeycaps(1X)							dxkeycaps(1X)



NAME

  dxkeycaps - Graphically display and edit the keyboard	mapping

SYNOPSIS

  dxkeycaps [-options]

OPTIONS

  Run dxkeycaps	with no	command	line options to	edit the keyboard mapping of
  the keyboard that is attached	to your	workstation.

  The dxkeycaps	command	accepts	all of the standard toolkit options. It	also
  accepts the following	options:

  -keyboard keyboard-name or -kbd keyboard-name
      Specifies	the type of keyboard to	display.  There	are many different
      types of computer	keyboards, and to function correctly dxkeycaps must
      know which one you are using. The	following keyboards are	known:


	   LK401 (American)	 LK401 (Svenska)       LK444 (Dansk)
	   LK201 (American)	 LK401 (Vlaams)	       LK444 (Deutsch)
	   LK443 (American)	 LK201 (Dansk)	       LK444 (Schweiz)
	   LK421		 LK201 (Deutsch)       LK444 (British/Irish)
	   LK401 (Dansk)	 LK201 (Schweiz)       LK444 (Espanol)
	   LK401 (Deutsch)	 LK201 (UK)	       LK444 (Francais)
	   LK401 (Schweiz)	 LK201 (Espanol)       LK444 (Canadien)
	   LK401 (British/Irish) LK201 (Francais)      LK444 (SuisseRomande)
	   LK401 (Espanol)	 LK201 (Canadien)      LK444 (Italiano)
	   LK401 (Francais)	 LK201 (SuisseRomande) LK444 (Nederlands)
	   LK401 (Canadien)	 LK201 (Italiano)      LK444 (Norsk)
	   LK401 (SuisseRomande) LK201 (Nederlands)    LK444 (Portugues)
	   LK401 (Italiano)	 LK201 (Norsk)	       LK444 (Suomi)
	   LK401 (Nederlands)	 LK201 (Portugues)     LK444 (Svenska)
	   LK401 (Norsk)	 LK201 (Suomi)	       LK444 (Vlaams)
	   LK401 (Portugues)	 LK201 (Svenska)
	   LK401 (Suomi)	 LK201 (Vlaams)

	   PCXAL (American)	 PCXAL (Dansk)	       PCXAL (Deutsch)
	   PCXAL (Schweiz)	 PCXAL (British/Irish) PCXAL (Espanol)
	   PCXAL (Francais)	 PCXAL (Canadien)      PCXAL (SuisseRomande)
	   PCXAL (Italiano)	 PCXAL (Nederlands)    PCXAL (Norsk)
	   PCXAL (Portugues)	 PCXAL (Suomi)	       PCXAL (Svenska)
	   PCXAL (Vlaams)

	   NCD N101		 NCD N102	       NCD N102sf
	   NCD N108		 NCD N97	       NCD vt220

      If the console's keyboard	language parameter is set correctly, dxkey-
      caps will	select the correct keyboard by default if run without any
      command line parameter. (Use the set language command to set the
      console's	keyboard language. See the section on environment variables
      in your workstation user's guide.)

      You may specify a	different flavor of the	"correct" keyboard (i.e., on
      a	workstation with an LK401, you can  specify the	LK421, LK443 or
      LK201), but you cannot display a PCXAL or	NCD keyboard layout unless
      you are displaying on a machine with those keyboards attached.

      If you specify
	   % dxkeycaps -kbd "pcxal (British/Irish)"

      the British/Irish	keyboard layout	is displayed. If you specify
	   % dxkeycaps -kbd pcxal

      the PCXAL	(American) keyboard layout is displayed	as the default.	If
      you specify
	   % dxkeycaps -kbd badkeyboardname

      the keyboard displayed is	the "best guess" at the	correct	default	key-
      board (based on kernel and console environment information), just	as if
      you ran dxkeycaps	without	any parameters at all.

      Case does	not matter when	specifying a keyboard name, but	you must
      quote keyboard names that	contain	spaces.	For example:
	   % dxkeycaps -kbd "PCXAL-AE (United Kingdom)"

  -gutterwidth number or -gw number
      Specifies	the number of pixels of	space to leave between each key.

DESCRIPTION

  The dxkeycaps	command	displays a keyboard with keycaps drawn according to
  the current server keymap.  When you move the	mouse over a key, the command
  describes the	key symbols and	modifiers that the key generates.  Clicking
  MB1 on a key simulates pressing a key. Clicking MB3 on a key brings up a
  menu of operations, including	a command to change the	key symbol that	the
  key generates.

  This program is, in part, a graphical	front-end to xmodmap.

  Display


  The bottom part of the window	is a drawing of	a keyboard.  In	the top	left
  of each key is printed the string which actually appears on the surface of
  the key.  In the bottom right	of the key is the (hexadecimal)	keycode	that
  this key generates.

  At the top of	the screen are several lines of	text describing	the key	under
  the mouse (or	the most recently typed	key.)  These lines are:

  KeyCode:
      Displays the text	printed	on the physical	key, and the keycode gen-
      erated by	that key in hex, decimal, and octal.

  KeySym:
      Displays the set of Key symbols that this	key currently generates.

  Modifiers:
      Displays the modifier bits that this key generates.  If a	key generates
      modifiers, it is a chord-key like	Shift or Control.

  AutoRepeat:
      States whether the X server claims that this key autorepeats.



  Commands Pull-Down Menu


  The Commands pull-down menu in the upper left	corner of the window contains
  the menu items Keyboard, Reset to Default, Save, and Exit:

  Keyboard
      Brings up	a menu from which you can change which keyboard	is displayed.
      For machines with	PC class keyboards, this menu offers the options of


	   PCXAL (American)
	   PCXAL (Dansk)
	   PCXAL (Deutsch)
	   PCXAL (Schweiz)
	   PCXAL (British/Irish)
	   PCXAL (Espanol)
	   PCXAL (Francais)
	   PCXAL (Canadien)
	   PCXAL (SuisseRomande)
	   PCXAL (Italiano)
	   PCXAL (Nederlands)
	   PCXAL (Norsk)
	   PCXAL (Portugues)
	   PCXAL (Suomi)
	   PCXAL (Svenska)
	   PCXAL (Vlaams)

      If you run dxkeycaps on a	workstation with no command line arguments,
      you get a	pullright menu for your	system's keyboard.  dxkeycaps detects
      what type	of keyboard you	have on	your system and	limits your choices.
      However, if, in the command line,	you specify a keyboard,	(even if it's
      the one attached to the display),	or use the -all	parameter, the Key-
      board menu item will display a two-level pullright, where	the first
      level for	an LK-style keyboard is:


		LK401>
		LK201>
		LK443>
		LK421

      Selecting	one of those produces the sub-menu of international variants
      described	above. An exception is the LK421, which	does not provide
      international support. If	you select LK421 from the first	level menu,
      the LK421	keyboard is displayed.

  Reset	to Default
      This command restores the	keyboard to its	default	state as defined by
      the physical keycaps on the keyboard. If you execute this	command	while
      displaying a keyboard that is not	the type of keyboard you are really
      using, your keymap will be in a nonsensical state.  There	is no way for
      dxkeycaps	to tell	what keyboard you are using.

  Save
      This command writes an xmodmap input file	representing the current
      state of the keyboard (including all of your changes) to the standard
      output. The file is saved	in your	home directory as ~/.dxkeycaps.	It
      prompts you with a dialog	box: you can either write an xmodmap file
      representing the state of	every key, or you can write a smaller file
      which describes only the changes.

  Exit
      Exits the	program.

  You can arrange for these bindings to	be installed each time you log in by
  placing an xmodmap command in	your .X11Startup file. For example:

	  xmodmap ~/.dxkeycaps


  Typing a key on the real keyboard simulates a	KeyPress/KeyRelease event
  pair in the same way that clicking on	a key does.

  You can also combine mouse and keyboard input: for example, if you use the
  mouse	to select the Shift key, and type a character, the event that is
  simulated will have the Shift	modifier set.  And if you hold down the	real
  Control key, and click on the	C key in the window, a Control-C event will
  be generated.	 (Assuming that	your window manager does not intercept
  control-left-button for its own purposes.)

  Clicking MB3 on a key	pops up	a menu of commands for the given key.  They
  are:

  Edit KeySyms of Key
      This pops	up the "Edit Key" window, which	allows you to arbitrarily
      change which key symbols and modifiers this key generates.

      On the left side of the window is	the list of the	key symbols that this
      key currently generates.	(A key may generate up to eight	key symbols;
      the interpretation of these key symbols is described in the X protocol
      document,	and is summarized here in the KEYSYMS AND KEYCODES section.)

      The second column	is a multiple-choice list of the eight modifier	bits
      that this	key may	generate.  For example,	if you want a key to behave
      as a Control key,	you should select the Control modifier.

      The third	and fourth column (the scrolling lists)	are for	changing the
      key symbol associated with the key.  When	you select a keysym-position
      from the first column, the character set and keysym will be displayed
      in the scrolling lists.  Clicking	on a key symbol	in the KeySym column
      will install that	key symbol in the highlighted slot in the first
      column.

      To select	a key symbol from a different character	set, click on the
      character	set name in the	second column.	(The Latin1 and	Keyboard
      character	sets are the most commonly used.)

      At the bottom of the window are three buttons: Undo, Abort, and Ok.
      Clicking on Undo reverts the Edit	Key window to the current state	of
      the key in question.  Clicking on	Abort closes the Edit Key window
      without making any changes. Clicking on Ok closes	the Edit Key window
      and installs your	changes	(the current keyboard mapping is modified.)

  Exchange Keys
      After selecting this menu	item, you are asked to click on	another	key.
      That key and the key on which you	brought	up the menu will be
      exchanged. This actually changes the current keyboard mapping.

  Duplicate Key
      After selecting this menu	item, you are asked to click on	another	key.
      That key will be made a copy of the key on which you brought up the
      menu. That is, the two keys will generate	the same set of	key symbols
      and modifiers. This actually changes the current keyboard	mapping	and
      redraws the keyboard with	the changed keycap reflecting its new status.

  Disable Key
      The key on which you brought up the menu will be made to generate	no
      keysyms and no modifiers.	This actually changes the current keyboard
      mapping and redraws the keyboard with the	changed	keycap reflecting its
      new status.

  Reset	Key To Default
      The key on which you brought up the menu will be restored	to its
      default state; no	other key will be altered. This	actually changes the
      current keyboard mapping and redraws the keyboard	with the changed key-
      cap reflecting its new status.

X DEFAULTS

  The dxkeycaps	command	understands all	of the core resource names and
  classes as well as:

  *Keyboard.keyboard (class Keyboard)
      Which keyboard to	display; this is the same as the -keyboard command-
      line option.  If this is not specified, the default keyboard is
      guessed, based on	the server's vendor identification string.  dxkeycaps
      can distinguish between the LK and PC class keyboards, and will not
      allow displaying or editing the LK keyboard on a workstation that	has a
      PC keyboard (or vice-versa).

  *Keyboard.Key.highlight (class Background)
      The color	to use to highlight a key when it is depressed.	 If this is
      the same as the background color of the key, it is highlighted with a
      stipple pattern instead.

  *Keyboard.Key.keycapColor (class Foreground)
      The color	to paint the keycap string.

  *Keyboard.Key.keycodeColor (class Foreground)
      The color	to paint the keycode number.

  *Keyboard.Key.borderColor (class Color)
      The color	of the box around each key.

  *Keyboard.Key.keycapFont (class Font)
      The font to use to draw the keycap string.

  *Keyboard.Key.keycodeFont (class Font)
      The font to use to draw the keycode number.

  *Keyboard.Key.borderWidth (class Int)
      The thickness of the box around each key.

  *Keyboard.Key.gutterWidth (class Int)
      How many pixels to leave between this key	and its	neighbors to the
      right and	bottom.

  The class of each key	widget is Key as indicated in the previous list.  The
  name of each key is the string(s) printed on its face. For example, if you
  wanted the Shift keys	to have	wider borders, you could specify:

	  DXkeycaps*Keyboard.Shift.borderWidth:	2

ACTIONS

  It is	possible to rebind the actions that happen when	 you press or release
  a key	or mouse button. These actions are available on	the Keyboard widget:

  HighlightKey(condition, arg)
      This places the key in question in the highlighted state.

      If no argument is	passed to this action, then the	key is determined by
      the event	which invoked this action.  If this action is invoked by a
      KeyPress or KeyRelease event, the	key-widget is the key corresponding
      to the key that the event	represents.  If	it is a	ButtonPress, Button-
      Release, or PointerMotion	event, then the	key-widget is the one under
      the mouse.

      The argument may be one of the words mouse, highlighted, or displayed,
      meaning the key under the	mouse, the key most recently highlighted, or
      the key currently	being described	in the "Info" area at the top of the
      window, respectively.

      The condition may	be one of the words ifmod, unlessmod, iftracking,
      unlesstracking, ifhighlighted, or	unlesshighlighted.  If ifmod was
      specified	and the	key in question	(as determined by the argument or by
      the invoking event) is not a modifier key, then this action is not exe-
      cuted.  The unlessmod condition is the opposite.	The iftracking and
      unlesstracking conditions	allow you to do	some actions only if (or
      unless) the key is being "tracked" with the mouse	(see below.)  The
      ifhighlighted and	unlesshighlighted actions allow	you to do some things
      only if (or unless) the key in question is currently in the highlighted
      state.

  UnhighlightKey(condition, arg)
      This places the key in question in the unhighlighted state.  Arguments
      are as above.

  ToggleKey(condition, arg)
      This makes the key be highlighted	if it is unhighlighted,	or
      unhighlighted if it is highlighted.  Arguments are as above.

  SimulateKeyPress(condition, arg)
      This action makes	a KeyPress event corresponding to the key be syn-
      thesized on the focus window.  Arguments are as above.

  SimulateKeyRelease(condition,	arg)
      This action makes	a KeyRelease event corresponding to the	key be syn-
      thesized on the focus window.  Arguments are as above.

  TrackKey(condition, arg)
      This makes the key in question begin being "tracked," which means	that
      moving the mouse off of it will simulate a button-release	action,	and
      then will	simulate a button-press	action on the key that the mouse has
      moved on to.  This action	may only be invoked from a ButtonPress or
      ButtonRelease event.

  UntrackKey(condition,	arg)
      This makes the key in question no	longer be "tracked."

  DescribeKey(condition, arg)
      This action causes the key and its bindings to be	displayed in the
      "Info" section at	the top	of the window, if it is	not already described
      there.

  The default actions for the Keyboard widget are:

       <Motion>:   DescribeKey(mouse,unlessTracking)	  \n\
       \
       <KeyDown>:  HighlightKey()			  \
		   DescribeKey(unlessMod)		  \
		   DescribeKey(displayed)		  \
		   SimulateKeyPress()			  \n\
       \
       <KeyUp>:	   UnhighlightKey()			  \
		   DescribeKey(displayed)		  \
		   SimulateKeyRelease()			  \n\
       \
       <Btn1Down>: HighlightKey(unlessMod)		  \
		   ToggleKey(ifMod)			  \
		   TrackKey(unlessMod)			  \
		   SimulateKeyPress(ifHighlighted)	  \
		   SimulateKeyRelease(unlessHighlighted)  \n\
       \
       <Btn1Up>:   UntrackKey(highlighted)		  \
		   SimulateKeyRelease(highlighted,unlessMod) \
		   UnhighlightKey(highlighted,unlessMod)  \n\
       \
       <Btn3Down>: XawPositionSimpleMenu(keyMenu)	  \
		   MenuPopup(keyMenu)			  \n

  If you do not	want a key to be described each	time the mouse moves over it,
  you can remove the <&lt;Motion>&gt; action.  In that case, you should	probably add
  DescribeKey()	to the <&lt;Btn1Down>&gt; and <&lt;KeyDown>&gt;	actions.

  If you want the key under the	mouse to be described even while the mouse is
  moving with a	button down, then remove the unlessTracking parameter from
  the DescribeKey action bound to <&lt;Motion>&gt;.

  If you do not	want the modifier keys to toggle, change the Button1 actions
  to the following:

       DXkeycaps*Keyboard.actions:  #override		    \
	       <Btn1Down>: HighlightKey()		   \
			   TrackKey(unlessmod)		   \
			   SimulateKeyPress()		   \n\
	       <Btn1Up>:   UntrackKey(highlighted)	   \
			   SimulateKeyRelease(highlighted) \
			   UnhighlightKey(highlighted)	   \n


  Remember that	these actions exist on the Keyboard widget, not	on the Key
  widgets.  If you add actions to the Key widgets, things will malfunction.

KEYSYMS	AND KEYCODES

  The following	description is from the	X Protocol document, and is reprinted
  here for your	convenience:

  A list of KeySyms is associated with each KeyCode. If	that list (ignoring
  trailing NoSymbol entries) is	a single KeySym	"K", then the list is treated
  as if	it were	the list "K NoSymbol K NoSymbol". If the list (ignoring
  trailing NoSymbol entries) is	a pair of KeySyms "K1 K2", then	the list is
  treated as if	it were	the list "K1 K2	K1 K2".	 If the	list (ignoring trail-
  ing NoSymbol entries)	is a triple of KeySyms "K1 K2 K3", then	the list is
  treated as if	it were	the list "K1 K2	K3 NoSymbol".

  The first four elements of the list are split	into two groups	of KeySyms.
  Group	1 contains the first and second	KeySyms, Group 2 contains third	and
  fourth KeySyms.  Within each group, if the second element of the group is
  NoSymbol, then the group should be treated as	if the second element were
  the same as the first	element, except	when the first element is an alpha-
  betic	KeySym K for which both	lowercase and uppercase	forms are defined.
  In that case,	the group should be treated as if the first element were the
  lowercase form of "K"	and the	second element were the	uppercase form of
  "K".

  The standard rules for obtaining a KeySym from a KeyPress event make use of
  only the Group 1 and Group 2 KeySyms;	no interpretation of other KeySyms in
  the list is given here.  (That is, the last four KeySyms are unused.)

  Which	group to use is	determined by modifier state.  Switching between
  groups is controlled by the KeySym named Mode_switch.

  By attaching that KeySym to some KeyCode and attaching that KeyCode to any
  one of the modifiers Mod1 through Mod5.  This	modifier is called the "group
  modifier." For any KeyCode, Group 1 is used when the group modifier is off,
  and Group 2 is used when the group modifier is on.

  Within a group, which	KeySym to use is also determined by modifier state.
  The first KeySym is used when	the Shift and Lock modifiers are off.  The
  second KeySym	is used	when the Shift modifier	is on, or when the Lock
  modifier is on and the second	KeySym is uppercase alphabetic,	or when	the
  Lock modifier	is on and is interpreted as ShiftLock.	Otherwise, when	the
  Lock modifier	is on and is interpreted as CapsLock, the state	of the Shift
  modifier is applied first to select a	KeySym,	but if that KeySym is lower-
  case alphabetic, then	the corresponding uppercase KeySym is used instead.

MODIFIER MAPPING

  The following	description is from the	InterClient Communications Conven-
  tions	Manual:

  X11 supports eight modifier bits, three  of which are	pre-assigned to
  Shift, Lock and Control.  Each modifier bit is controlled by the state of a
  set of keys, and these sets are specified in a table accessed	by GetModifi-
  erMapping() and SetModifierMapping().

  A client needing to use one of the pre-assigned modifiers should assume
  that the modifier table has been set up correctly to control these modif-
  iers.	 The Lock modifier should be interpreted as Caps Lock or Shift Lock
  according as the keycodes in its controlling set include XK_Caps_Lock	or
  XK_Shift_Lock.

  Clients should determine the meaning of a modifier bit from the keysyms
  being	used to	control	it.

  A client needing to use an extra modifier,  for example Meta,	 should:

  Scan the existing modifier mappings. If it finds a modifier that contains a
  keycode whose	set of keysyms includes	XK_Meta_L or XK_Meta_R,	it should use
  that modifier	bit.

  If there is no existing modifier controlled by XK_Meta_L or XK_Meta_R, it
  should select	an unused modifier bit (one with an empty controlling set)
  and:

  If there is a	keycode	with XL_Meta_L in its set of keysyms, add that key-
  code to the set for the chosen modifier, then

  if there is a	keycode	with XL_Meta_R in its set of keysyms, add that key-
  code to the set for the chosen modifier, then

  if the controlling set is still empty,  interact with	the user to select
  one or more keys to be Meta.

  If there are no unused modifier bits,	ask the	user to	take corrective
  action.

  This means that the Mod1 modifier does not necessarily mean Meta, although
  some applications (such as twm and emacs) assume that. Any of	the five
  unassigned modifier bits could mean Meta; what matters is that a modifier
  bit is generated by a	keycode	which is bound to the keysym Meta_L or Meta-
  R.

  Therefore, if	you want to make a "meta" key, the best	way is to make the
  keycode in question generate both a Meta keysym, and a modifier bit.








RESTRICTIONS

  Because this program has default colors that are not "black and white," the
  -rv command-line option does not work.  But the following incantation	does
  what you want	on a monochrome	screen:

	  % dxkeycaps -fg white	-bg black -bd white

ENVIRONMENT VARIABLES

  DISPLAY
      Use this environment variable to get the default host and	display
      number.

  XENVIRONMENT
      Use this environment variable to get the name of a resource file that
      overrides	the global resources stored in the RESOURCE_MANAGER property.

SEE ALSO

  X(1X), xmodmap(1X)