'\"!  tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | tbl | eqn | tbl | tbl | tbl | tbl | tbl | tbl | tbl | mmdoc
'\"macro stdmacro
.if n .pH g3w.olVrtKeyBut @(#)olVrtKeyBut	40.3 of 1/8/90
.tr ~
.ds oS VIRTUAL
.nr oN 0
.nr X
.if \nX=0 .ds x} ""VIRTUAL KEY/BUTTON" 3W "\&"
.if \nX=1 .ds x} ""VIRTUAL KEY/BUTTON" 3W
.if \nX=2 .ds x} ""VIRTUAL KEY/BUTTON" "" "\&"
.if \nX=3 .ds x} ""VIRTUAL "" "" "\&"
.TH \*(x}
.SH "SYNOPSIS"
.nf
\s-1\f4#include <Intrinsic.h>
#include <OpenLook.h>
.P
\s-1\f4char *OlConvertVirtualTranslation(virtual_translation)
char *virtual_translation;\f1\s+1
.fi
.SH "DESCRIPTION"
.sp
\f3Converts Virtual Translations into Standard Translations\f1
.P
\f4OlConvertVirtualTranslation()\f1
takes a virtual translation string as input and returns a
standard X~Toolkit Intrinsic's translation string.
The function parses the input string replacing any virtual key
or button expressions with their real representation(s).
A virtual translation string has the same format as a standard
X~Toolkit Intrinsics translation string,
except that virtual expressions can appear as modifiers or
event types.
(However, a virtual expression cannot appear as an event type
detail.)
.P
.in +.4i
\f3Reference:\f1
.br
See "Appendix A" in the \f2X~Toolkit Intrinsics\(emC 
Language Interface,
X~Window System, X~Version 11, Release 2\f1, for more information
on the translation string.
.in -1i
.sp
\f3Virtual Expressions\f1
.P
Virtual expressions are key or mouse button names that are
independent of any physical mapping of the keyboard or mouse
buttons.
For instance,
MENU
(which in this document refers to the mouse button used to pop
up menus)
has the virtual expression
\f4menuBtn\f1
in a virtual translation.
If the end user has assigned mouse button three to be MENU,
then the
\f4OlConvertVirtualTranslation()\f1
routine would convert a virtual translation that contains the
expression
\f4menuBtn\f1
into a standard translation containing the expression
\f4Button3\f1.
.P
The following is the list of virtual expressions for the
various keys and mouse buttons defined in the OPEN LOOK user
interface.
The left column gives the name used in this document.
.TS
center box;
l c.
Name	Virtual Expression
_
.T&
l a.
ADJUST	adjustBtn
CANCEL	cancelBtn
CONSTRAIN	constrainBtn
COPY	copyKey
CUT	cutKey
DUPLICATE	duplicateBtn
HELP	helpKey
MENU	menuBtn
MENUDEFAULT	menuDefaultBtn
NEXTFIELD	nextFieldKey
PAN	panBtn
PASTE	pasteKey
PREVFIELD	prevFieldKey
PROPERTY	propertiesKey
SELECT	selectBtn
STOP	stopKey
UNDO	undoKey
.TE
.P
The following example illustrates a virtual translation that
contains three productions.
(The \f4Message\f1 production does not involve any virtual
translations but is included for illustration.)
.P
\f4" ! selectBtn <selectBtnUp>:    notify() \en
    <Message>:                  checkClientMessage() \en
  ! <copyKeyDown>:              copyToClipboard()"\f1
.sp
\f3Space Allocated Only If Necessary\f1
.P
If the input string does not contain any virtual expressions,
the original string is returned.
If the input string contains at least one valid virtual production,
the function allocates memory for the returned string.
The application is responsible for checking this difference
and freeing the allocated memory,
if appropriate.
.sp
\f3Invalid Productions Dropped\f1
.P
If the input string contains a valid virtual production,
any invalid virtual productions are not included in the returned
string.  If the input string contains no virtual productions, 
error checking is not done.
